moai-lang-go

快速参考（30 秒）

Go 1.23+ 开发专家，专注于高性能后端系统和 CLI 应用。

自动触发：扩展名为 .go 的文件、go.mod、go.sum、goroutine、channel、Fiber、Gin、GORM、Echo、Chi

核心用例：

• 高性能 REST API 和微服务
• 并发和并行处理系统
• CLI 工具和系统实用程序
• 云原生容器化服务

快速模式：

Fiber API 模式：

调用 fiber.New 函数创建应用。定义 api/users/:id 路由，其处理函数接收 fiber.Ctx 并返回 error。在处理函数中，调用 c.JSON，并传入包含来自 c.Params 的 id 的 fiber.Map。调用 app.Listen 监听端口 3000。

Gin API 模式：

调用 gin.Default 函数创建 r。定义 api/users/:id 的 GET 路由，其处理函数接收 gin.Context 指针。在处理函数中，调用 c.JSON，并传入状态码 200 和包含来自 c.Param 的 id 的 gin.H。调用 r.Run 监听端口 3000。

带错误处理的 Goroutine：

调用 errgroup.WithContext 和 context.Background 创建 g 和 ctx。调用 g.Go，并传入返回 processUsers(ctx) 的函数。调用 g.Go，并传入返回 processOrders(ctx) 的函数。如果 g.Wait 返回的 err 不为 nil，则调用 log.Fatal 并传入该错误。

---

实现指南（5 分钟）

Go 1.23 语言特性

新特性：

• 使用 for i range 10 语法遍历整数并打印 i
• 配置文件引导优化（PGO）2.0
• 改进泛型，类型推断能力更强

泛型模式：

创建泛型 Map 函数，类型参数 T 和 U 的约束均为 any。接收 T 类型的切片和一个从 T 转换为 U 的函数。创建与输入长度相同的 U 类型结果切片。遍历该切片，并将函数作用于各个值的结果赋给对应的结果元素。返回结果。

Web 框架 Fiber v3

调用 fiber.New 创建应用，并传入包含 ErrorHandler 和 Prefork true 的 fiber.Config。使用 recover.New、logger.New 和 cors.New 中间件。在 api/v1 路径下创建 api 组。定义 listUsers、带 id 参数的 getUser、createUser、带 id 的 updateUser，以及带 id 的 deleteUser 路由。调用 app.Listen 监听端口 3000。

Web 框架 Gin

调用 gin.Default 创建 r。使用 cors.Default 中间件。在 api/v1 路径下创建 api 组。定义调用 listUsers 的 users GET 路由、调用 getUser 的 users/:id GET 路由，以及调用 createUser 的 users POST 路由。调用 r.Run 监听端口 3000。

请求绑定模式：

定义 CreateUserRequest 结构体，包含 Name 和 Email 字段。添加 json 标签，以及用于必填、最小长度为 2 和必填邮箱验证的 binding 标签。在 createUser 处理函数中，声明 req 变量，并调用 c.ShouldBindJSON，传入指针。如果出错，调用 c.JSON，传入 400 状态码和错误信息。否则，调用 c.JSON，传入 201 和响应数据。

Web 框架 Echo

调用 echo.New 创建 e。使用 middleware.Logger、middleware.Recover 和 middleware.CORS。在 api/v1 路径下创建 api 组。定义 users 的 GET 和 POST 路由。调用 e.Logger.Fatal，并传入 e.Start 在端口 3000 上启动服务。

Web 框架 Chi

调用 chi.NewRouter 创建 r。使用 middleware.Logger 和 middleware.Recoverer。调用 r.Route，传入 api/v1 路径和函数。在函数内部，调用 r.Route 并传入 users 路径。定义用于列表查询的 Get、用于创建的 Post，以及带 id 参数、用于查询单个用户的 Get。调用 http.ListenAndServe，传入端口 3000 和 r。

ORM GORM 1.25

模型定义：

定义 User 结构体，并嵌入 gorm.Model。为 Name 添加 uniqueIndex 和 not null 标签，为 Email 添加 uniqueIndex 和 not null 标签，并为 Posts 切片添加 foreignKey AuthorID 标签。

查询模式：

调用 db.Preload，传入 Posts 和一个函数，该函数按 created_at 降序排序并限制为 10 条，然后调用 First，传入 user 和 id 1。对于事务，调用 db.Transaction，并传入接收 tx 指针的函数。在函数内部，创建用户和个人资料，并返回任何错误。

使用 sqlc 编写类型安全的 SQL

创建 sqlc.yaml，设置版本为 2，在 sql 部分指定 postgresql 引擎、查询和架构路径，并设置 Go 生成选项，包括包名、输出目录和 pgx v5 sql_package。

在 query.sql 文件中，添加名为 GetUser 的查询，通过匹配参数中的 id 返回所有列。添加名为 CreateUser 的查询，插入 name 和 email 值并返回所有列。

并发模式

Errgroup 模式：

使用 errgroup.WithContext 创建 g 和 ctx。调用 g.Go 执行 fetchUsers，并将结果赋给 users 变量。调用 g.Go 执行 fetchOrders，并将结果赋给 orders 变量。如果 g.Wait 返回错误，则返回 nil 和该错误。

工作池模式：

定义 workerPool 函数，接收只读 jobs 通道、只写 results 通道和工作线程数量 n。创建 WaitGroup。循环 n 次，每次递增 WaitGroup 计数并启动一个 goroutine；该 goroutine延迟调用 Done，遍历 jobs，并将 processJob 的结果发送到 results。等待所有任务完成，然后关闭 results。

带超时的 Context：

使用 context.WithTimeout 创建 ctx 和 cancel，超时时间为 5 秒。延迟调用 cancel。使用 ctx 调用 fetchData。如果错误为 context.DeadlineExceeded，则返回超时响应和 StatusGatewayTimeout。

测试模式

表驱动测试：

定义 tests 切片，其元素为包含 name 字符串、input CreateUserInput 和 wantErr 布尔值的结构体。添加有效输入和 name 为空的测试用例。遍历 tests，调用 t.Run，并传入 name 和测试函数。调用 service.Create；如果 wantErr 为 true，则使用 require.Error 检查错误。

HTTP 测试：

使用 fiber.New 创建 app。添加 GET 路由 users/:id，并调用 getUser。使用 httptest.NewRequest 创建一个针对 users/1 的 GET 请求。调用 app.Test 并传入请求，以获取响应。断言状态码为 200。

使用 Cobra 和 Viper 构建 CLI

将 rootCmd 定义为 cobra.Command 指针，并设置 Use 和 Short 字段。在 init 函数中，为 cfgFile 添加 PersistentFlags StringVar。调用 viper.BindPFlag，传入 config 和 lookup。将 viper.SetEnvPrefix 设置为 MYAPP，并调用 viper.AutomaticEnv。

---

高级模式

如需全面了解以下内容：

• 高级并发模式（工作池、速率限制、errgroup）
• 泛型和类型约束
• 接口设计与组合
• 全面的测试模式（TDD、表驱动测试、基准测试、模糊测试）
• 性能优化和性能分析

请参阅：reference/advanced.md 了解高级模式，reference/testing.md 了解测试模式。

性能优化

PGO 构建：

启用 GODEBUG pgo 运行应用，并输出 cpuprofile。使用 go build 构建，并通过 pgo 标志指定配置文件。

对象池：

将 bufferPool 创建为 sync.Pool，并设置 New 函数返回一个 4096 字节的切片。使用类型断言获取缓冲区，并延迟调用 Put 将其归还到池中。

容器部署 10-20MB

多阶段 Dockerfile：第一阶段使用 golang:1.23-alpine 作为构建器，设置 WORKDIR，复制 go.mod 和 go.sum，运行 go mod download，复制源代码，并使用 CGO_ENABLED 0 和用于生成精简二进制文件的 ldflags 进行构建。第二阶段使用 scratch，复制二进制文件并设置 ENTRYPOINT。

优雅关闭

启动一个调用 app.Listen 的 goroutine。创建一个用于接收 os.Signal 的 quit 通道，缓冲区大小为 1。调用 signal.Notify 监听 SIGINT 和 SIGTERM。从 quit 接收信号后，调用 app.Shutdown。

---

Context7 库

• golang/go：Go 语言和标准库
• gofiber/fiber：Fiber Web 框架
• gin-gonic/gin：Gin Web 框架
• labstack/echo：Echo Web 框架
• go-chi/chi：Chi 路由器
• go-gorm/gorm：GORM ORM
• sqlc-dev/sqlc：类型安全的 SQL
• jackc/pgx：PostgreSQL 驱动
• spf13/cobra：CLI 框架
• spf13/viper：配置管理
• stretchr/testify：测试工具包

---

配合使用效果良好

• moai-domain-backend：REST API 架构和微服务
• moai-lang-rust：系统编程搭档
• moai-quality-security：安全加固
• moai-essentials-debug：性能分析
• moai-workflow-ddd：领域驱动开发

---

故障排除

常见问题：

• 模块错误：运行 go mod tidy 和 go mod verify
• 版本检查：运行 go version 和 go env GOVERSION
• 构建问题：运行 go clean -cache 和 go build -v

性能诊断：

• CPU 性能分析：运行 go test -cpuprofile cpu.prof -bench .
• 内存性能分析：运行 go test -memprofile mem.prof -bench .
• 竞态检测：运行 go test -race ./...

---

其他资源

有关高级并发模式、泛型和接口设计，请参阅 reference/advanced.md。

有关全面的测试模式（包括 TDD、基准测试和模糊测试），请参阅 reference/testing.md。

---

最后更新：2026-01-11 版本：1.1.0