Home

深色模式

Goa 代码生成 ​

概述 ​

Goa 真正的日常工作流，不是“生成一次代码然后忘掉它”，而是围绕 design 持续生成、持续实现。中小项目里，把 goa gen 和 goa example 的职责分清，能少掉很多无意义的折腾。

说白一点：goa gen 是常用命令，goa example 是起步命令。两者都重要，但不是同一个用途。

goa gen 和 goa example 的差别 ​

goa gen ​

goa gen 是主命令，用来根据 DSL 重新生成代码。官方文档说明，它会重新创建整个 gen/ 目录。

sh
goa gen example.com/blogapi/design

执行后会生成这些内容：

  • 服务接口类型
  • endpoint 层
  • HTTP 或 gRPC 传输层
  • OpenAPI 文档
  • 客户端代码

它应该在每次设计变更后执行。

goa example ​

goa example 更像脚手架命令，用来生成一套起步实现。

sh
goa example example.com/blogapi/design

它通常会生成：

  • cmd/ 下的启动代码
  • 一个示例实现文件
  • 可运行的最小服务骨架

官方文档也明确提到，example 生成的是你接管的实现骨架，后续不会像 gen/ 一样每次都被覆盖。

命令参数别写错 ​

Goa 的命令接收的是 Go 包导入路径，不是文件系统路径。

正确写法：

sh
goa gen example.com/blogapi/design

错误写法：

sh
goa gen ./design

如果命令行里习惯性写相对路径，这里很容易顺手写错。这个坑不大，但很常见。

生成出来的目录怎么看 ​

一个典型项目大致会长这样：

text
blogapi/
├── cmd/
│   └── api/
├── design/
│   ├── api.go
│   └── user.go
├── gen/
│   ├── user/
│   └── http/
│       ├── user/
│       └── openapi.json
└── internal/

其中最重要的边界是：

  • design/：你写
  • gen/：Goa 生成
  • internal/：你写
  • cmd/：你接管

把这几层混了，后面改接口时就会很痛苦。

哪些文件能改，哪些别改 ​

可以改的：

  • design/ 下的设计文件
  • cmd/ 下自己维护的启动代码
  • internal/ 下的业务、仓储、鉴权、配置代码
  • goa example 生成后由你接管的实现文件

不要手改的：

  • gen/ 下所有由 goa gen 生成的文件

如果手改 gen/，下一次生成时这些修改大概率就没了。更麻烦的是，团队里别人未必知道你改过，代码审查时也很难分清哪些是生成差异，哪些是手工逻辑。

中小项目里最省事的生成流程 ​

一个比较顺手的节奏通常是这样：

新项目起步 ​

sh
goa gen example.com/blogapi/design
goa example example.com/blogapi/design
go mod tidy

日常改接口 ​

sh
goa gen example.com/blogapi/design
go build ./...

也就是说：

  • 第一次起项目，gen 和 example 都跑
  • 后面改接口，通常只跑 gen
  • 编译通过，再继续写业务实现

很多人会问：新增一个方法后，要不要再跑一次 example？中小项目里通常没这个必要。自己补实现文件，往往比反复依赖脚手架更直接。

生成代码要不要提交版本库 ​

按 Goa 官方代码生成文档的建议，生成代码可以直接提交到版本库。这对中小项目尤其有好处：

  • 构建更可重复
  • 代码审查时能直接看到设计变更带来的影响
  • 部署环境不需要额外安装 Goa CLI 再生成一遍

如果团队已经接受“生成代码也是源码的一部分”，那这条路线通常最省心。

常见误区 ​

把 goa gen 当成一次性脚手架 ​

Goa 不是只在项目开始时跑一次生成命令。只要接口契约变了，就应该重新生成。

指望 example 负责长期维护 ​

example 适合起步，不适合当持续开发主流程。业务实现还是要自己接管。

只看 OpenAPI，不看生成接口 ​

Goa 的真正约束力不只在文档上，也在生成出来的 Go 类型和方法签名上。编译期约束，往往比文档提醒更有力。

参考 ​