go-micro 快速入门指南：5 分钟创建并运行你的第一个微服务

go-micro 快速入门指南5 分钟创建并运行你的第一个微服务【免费下载链接】go-microA Go agent harness and service framework项目地址: https://gitcode.com/gh_mirrors/go/go-micro导读本文是 go-micro一个 Go 语言 agent harness 与服务框架的官方快速入门手册的完整实战版。你将学会在 5 分钟内完成microCLI 的安装、用一条命令脚手架出第一个服务、在本地以热重载方式运行并通过 HTTP 调用验证随后沿着服务 → Agent → 工作流的上坡路径on-ramp走向 Agent 开发同时掌握 RPC 服务、事件发布/订阅三大核心编码模式。一、安装microCLIgo-micro 提供了两条官方安装路径按你的环境任选其一。注意两条路径的适用前提不同二进制安装器不需要 Go 工具链即可完成安装而源码安装要求本机已有 Go。方式一预编译二进制推荐无需 Go 工具链curl -fsSL https://go-micro.dev/install.sh | sh该方式直接下载已发布的micro可执行文件安装阶段完全不依赖 Go。需要留意的是虽然安装本身不需要 Go但后续执行micro run构建并运行生成的服务时仍然需要本机装有 Go 工具链Go 1.24 或更新版本。方式二Go 源码安装go install go-micro.dev/v6/cmd/microlatest该方式适用于本机已有 Go 的环境二进制会被安装到$(go env GOPATH)/bin目录下。CLI 的入口实现位于仓库 cmd/micro/main.go它通过cmd.Init以micro为命令名初始化并链接了cmd/defaults与a2a、ai、chat、cli、flow、gateway、inspect、loop、mcp、run等全部插件因此--registry etcd、--broker nats、--profile nats这类插件旗标开箱即用。安装后的验证如果安装器执行完毕但 shell 找不到micro命令请务必在创建第一个服务之前完成排障。先确认命令解析与版本command -v micro micro --version常见问题与修复见下表完整版参考仓库文档 internal/website/content/en/docs/guides/install-troubleshooting.md症状检查项修复方法micro: command not foundcommand -v micro把安装目录加入PATH后打开新终端重试。常见目录export PATH$HOME/.micro/bin:$PATH二进制安装器或export PATH$(go env GOPATH)/bin:$PATHgo installmicro run找不到 Gogo version安装 Go 1.24 或更新版本网关端口被占用lsof -i :8080停止占用端口的进程或改用其他地址运行Agent 运行被 provider-key 错误阻塞micro agent preflight先停留在无密钥路径上运行micro agent demo再跟随无密钥 first-agent 指南二、创建你的第一个服务安装完成后用两条命令完成服务创建与本地启动# 创建新服务 micro new helloworld cd helloworld # 查看生成的代码 ls -la # 本地运行默认开启热重载 micro run # 测试服务 curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call \ -H Content-Type: application/json \ -d {name: World}预期输出形如{msg:Hello World}。这里的micro new、micro run、API 网关的运行时行为都来自仓库源码值得逐一看懂micro new到底生成了什么从 cmd/micro/cli/new/new.go 的Run实现可以确认默认采用反射式protoless模板生成的main.go、handler/helloworld.go通过反射注册 handler不需要protoc工具链即可构建运行。对应文件集合为main.go、handler/、Makefile、README.md、.gitignore、go.mod。生成过程自动执行go mod tidy解析依赖随后打印项目结构树与下一步指引。生成服务与 CLI 保持同版本microVersion()会从构建信息中读取 CLI 所使用的 go-micro 版本写入生成的go.mod确保生成的服务依赖与你正在运行的框架版本一致本地 dev 构建则回退到latest。micro new还提供若干实用旗标源码见new.go中的 Flags 定义旗标作用--template服务模板default、crud、pubsub、api后三者基于 proto--proto使用 Protocol Buffers需要protoc默认反射式无需 protoc--no-mcp禁用生成代码中的 MCP 网关集成--prompt ...用 AI 设计并生成多个服务需要--provider与 API key或ANTHROPIC_API_KEY等环境变量如果选择--proto而本机缺少protoc、protoc-gen-go、protoc-gen-micro任一工具micro new不会报晦涩错误而是打印缺失清单与安装命令go install go-micro.dev/v6/cmd/protoc-gen-microlatest等。micro run的本地运行时micro run启动的是本地开发 harness。从 cmd/micro/run/run.go 的源码看热重载默认开启watchEnabled : !c.Bool(no-watch)可用--no-watch关闭内置文件监听器watcher会在源码变化时自动重建并重启服务。根据 cmd/micro/README.md 对本地运行时的说明micro run在localhost:8080上同时暴露API 网关http://localhost:8080/api/{service}/{method}即上面 curl 调用的入口Web 仪表盘http://localhost:8080Agent Playgroundhttp://localhost:8080/agentAPI Explorerhttp://localhost:8080/apiMCP Toolshttp://localhost:8080/mcp/tools健康检查http://localhost:8080/health在另一个终端里还可以用 CLI 直接调用服务方法进行验证micro call helloworld Helloworld.Call {name:World}三、核心编码模式在正式进入 Agent 开发之前掌握服务端最基本的三种编码模式。它们是 go-micro 框架的骨架也是后续服务即工具service-as-tool能力的基础。1. RPC 服务package main import ( context go-micro.dev/v6 ) type Greeter struct{} func (g *Greeter) Hello(ctx context.Context, req *Request, rsp *Response) error { rsp.Message Hello req.Name return nil } func main() { service : micro.NewService(greeter) service.Handle(new(Greeter)) service.Run() }要点解析micro.NewService(greeter)创建并命名一个服务它会自动完成注册中心默认内存 registry、RPC 编解码、请求路由等组件的初始化。service.Handle(new(Greeter))将 handler 注册到服务在默认反射式模式下方法名、参数结构都会成为可被 RPC 调用的端点无需额外写 proto 定义。在完整可运行示例中Request/Response通常由 proto 文件生成见 examples/hello-world/main.go而仓库的 examples/first-agent 演示了纯 Go struct 反射式注册的写法。2. Pub/Sub 事件订阅import ( context go-micro.dev/v6 ) func main() { service : micro.NewService(subscriber) // 订阅事件 micro.RegisterSubscriber(user.created, service.Server(), func(ctx context.Context, event *UserCreatedEvent) error { // 处理事件 return nil }, ) service.Run() }micro.RegisterSubscriber把处理器绑定到主题user.created上运行时会通过 broker默认内存 broker把事件投递给匹配的订阅者。3. 发布事件publisher : micro.NewEvent(user.created, client) publisher.Publish(ctx, UserCreatedEvent{ Email: userexample.com, })micro.NewEvent创建事件发布器Publish将消息发往 broker 的指定主题。服务之间通过主题 事件结构解耦生产者不感知订阅者订阅者也不感知生产者这正是 go-micro 事件驱动架构的典型形态。四、下一步services → agents → workflows 上坡路径micro run跑通之后你已经拥有了服务这一半生命周期。官方推荐按以下顺序继续上坡完整编号清单见原文档此处全部转换为仓库内可直达路径先排障安装Install troubleshooting—— 验证二进制安装器或go install、PATH、micro --version与无密钥 smoke 路径。micro agent demo—— 从已安装的 CLI 打印 provider-free 的 first-agent 演示命令与后续文档步骤。micro agent quickcheck或micro agent debug—— 当脚手架 → 运行 → 聊天 → 检查流程卡住时打印简短恢复地图。micro examples—— 按复制粘贴顺序打印维护中的可运行示例。micro zero-to-hero—— 打印维护中的一条命令、无密钥生命周期 harness 与可运行示例。Examples 导航索引—— 从一张地图里挑选最小的无密钥 first-agent、维护中的0→hero 支持参考examples/support以及后续互操作示例。最小 first-agent 示例—— 在配置 provider 密钥之前先用 mock 模型跑一个无密钥 Agent。无密钥 first-agent 实录—— 在配置 provider 密钥之前用 mock 模型运行一个实用的支持型 Agent。你的第一个 Agent—— 把这个服务改造成可被 Agent 调用的工具与它聊天并掌握micro agent preflight→micro run→micro chat循环。Agent 调试—— 当 Agent 行为异常时用micro inspect agent name检查服务注册、工具调用、运行历史、记忆、provider 故障与流程交接。0→hero 参考—— 走完经过 CI 验证的脚手架 → 运行 → 聊天 → 检查 → 部署 dry-run路径证明服务、Agent 与工作流三者协同。完成 first-agent 路径后可以继续分支到完整教程—— 深入指南示例—— 按服务、Agent、工作流映射的可运行示例部署—— 生产环境部署这些 CLI 命令的实现依据上述micro agent demo、micro agent quickcheck、micro examples、micro zero-to-hero、micro docs等命令均有真实实现Agent 子命令定义在 cmd/micro/cli/agent/agent.go含demo、quickcheck、preflight、doctor、list、history等子命令。micro examples、micro zero-to-hero、micro docs实现在 cmd/micro/cli/cli.go各自打印维护中的示例导航、无密钥生命周期演示命令与文档路径micro new、micro gen proto、micro services、micro call、micro describe也注册在同一个文件中。micro agent preflight与micro agent doctor前者在micro run之前做只读检查Go 版本、micro二进制、provider 密钥、默认本地网关端口全程不联系 provider失败项会给出Fix:与Next:指引后者在micro run已运行但聊天/网关/注册/inspect 异常时做运行后恢复检查实现见 cmd/micro/cli/agent/preflight.go 与 cmd/micro/cli/agent/doctor.go。把服务变成 Agent 工具在 your-first-agent 指南 中一个服务端点同时充当 RPC 方法、仪表盘/API 动作、MCP 工具与 Agent 工具——不需要为 Agent 编写第二套集成层。关键写法agent : micro.NewAgent(assistant, micro.AgentServices(task), micro.AgentPrompt(You help manage tasks. Use the task service before answering.), micro.AgentProvider(anthropic), micro.AgentAPIKey(os.Getenv(ANTHROPIC_API_KEY)), ) go agent.Run() service.Run()要点micro.AgentServices(task)把 Agent 的作用域限定到task服务方法上的文档注释与example标签会变成工具描述供模型正确选择task.Create、task.List因此给端点写注释不是可有可无的装饰。服务调用本身不需要模型密钥只有 Agent 需要推理选工具时才需要 provider 密钥。五、常见故障与帮助资源快速排障速查症状检查项处理建议micro: command not foundcommand -v micro将安装目录加入PATH并重开终端micro run无法找到 Gogo version安装 Go 1.24网关端口 8080 被占用lsof -i :8080停止占用进程或换地址运行Agent 无法访问服务micro agent list确认创建 Agent 时使用了micro.AgentServices(...)工具调用字段错误方法注释补全文档注释与example标签纯服务调用正常但聊天失败环境变量确认 provider key 已导出到运行micro run的 shell需要无密钥参考路径make harness在 go-micro 仓库根目录运行用 mock provider 走完服务→Agent→工作流生命周期帮助与文档资源仓库内示例导航examples/INDEX.md与 examples/README.md部署指南internal/website/content/en/docs/deployment/Agent 调试指南debugging-agents.md仓库贡献者可用make install-smoke在不联网的情况下针对本地构建跑一遍安装器 seammake harness则用 mock 模型验证完整的 services → agents → workflows 生命周期对应 harness 脚本位于 internal/harness/zero-to-hero-ci/run.sh。至此你已经完成了 go-micro 的安装、首个服务的创建与调用并掌握了 RPC 与事件两大核心模式。接下来沿着上坡路径构建你的第一个服务型 Agent就是水到渠成的事了。【免费下载链接】go-microA Go agent harness and service framework项目地址: https://gitcode.com/gh_mirrors/go/go-micro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考