Goa 是 Go 语言生态中"设计优先"的 API 框架——你用 DSL 描述服务，框架帮你生成 transport 层、OpenAPI 文档、客户端代码。这个思路本身很清晰，但当设计文件膨胀到几十个 service、上百个 method 时，代码生成就会变成一件痛苦的事：跑一次 goa gen 要等将近一分钟。v3.28.0 直接把这个问题砍到了 11 秒，同时还修了 OpenAPI 安全输出的准确性问题，并对齐了 Go 1.25 工具链。
生成加速：不再反复重算导入
核心改动在 issue #3932。旧流程中，每生成一批文件就会重新计算该批次的导入集合。如果你的设计包含 20 个 service，每个 service 触发一次导入重算，那就是 20 次重复遍历。对于大型项目（几百个 type、大量跨 service 引用），这个开销非常可观。
新版本的做法是：在生成开始前一次性算好完整的导入集合，后续每个批次直接引用这份全局结果，不再逐批重算。下游实测数据很直观——完整生成脚本从约 46 秒降到约 11 秒，提速约 76%。
这个改动对日常开发体验的影响比数字本身更大。大型 API 项目往往需要频繁迭代设计并重新生成，46 秒的等待会打断工作节奏；11 秒则接近"改完设计、跑一下、立刻看结果"的流畅感。
OpenAPI 安全输出更准确
Goa 的 DSL 支持用 Security() 声明认证方案（JWT、OAuth2、APIKey 等），并把这些声明映射到 OpenAPI 3.0 的 securitySchemes 和 security 字段。旧版本在某些场景下生成的 OpenAPI 文档与 DSL 声明不一致——比如一个 method 同时声明了多种安全方案时，输出可能遗漏或错配。
v3.28.0 修正了这些不一致，确保生成的 swagger.yaml / openapi.yaml 中安全声明与设计 DSL 严格对应。如果你之前靠手动修补 OpenAPI 文档来弥补这个偏差，现在可以去掉那层补丁了。
Go 1.25 工具链兼容
Go 1.25（当前开发分支）对模块系统和构建工具链有若干调整。Goa 的生成代码和 goa gen 命令本身需要在这些变化下正常工作。v3.28.0 已做了适配，确保在 Go 1.25 环境下生成和编译均无问题。如果你正在跟进上游工具链预览，这个版本可以直接用。
实践：用 Goa DSL 定义一个带安全声明的服务
下面是一个最小但完整的 Goa 设计示例，包含 JWT 安全声明和两个 method。你可以直接复制到项目中运行生成。
// design.go — Goa v3 设计文件
package design
import (
. "goa.design/goa/v3/dsl"
)
var _ = API("Bookshelf", func() {
Title("书架管理服务")
Description("简单的图书 CRUD API，演示 Goa 安全声明")
Version("1.0")
// 定义 JWT 安全方案
Security(JWT, func() {
Description("使用 JWT Bearer Token 认证")
Scope("read:books", "读取图书")
Scope("write:books", "修改图书")
})
})
var _ = Service("books", func() {
Description("图书管理服务")
// 方法级安全：列出图书需要 read:books 权限
Method("list", func() {
Security(JWT, func() {
Scope("read:books")
})
Result(CollectionOf(Book))
HTTP(func() {
GET("/books")
Response(StatusOK)
})
})
// 方法级安全：添加图书需要 write:books 权限
Method("create", func() {
Security(JWT, func() {
Scope("write:books")
})
Payload(func() {
Attribute("title", String, "书名")
Attribute("author", String, "作者")
Required("title", "author")
})
Result(Book)
HTTP(func() {
POST("/books")
Response(StatusCreated)
})
})
})
var Book = ResultType("application/vnd.goa.example.book", func() {
Attribute("id", Int, "图书 ID")
Attribute("title", String, "书名")
Attribute("author", String, "作者")
Required("id", "title", "author")
})
运行生成命令：
# 安装 Goa CLI（确保版本 >= v3.28.0）
go install goa.design/goa/v3/cmd/goa@v3.28.0
# 在项目根目录执行生成
goa gen design/design.go
# 查看生成的 OpenAPI 文档中安全声明是否正确
cat gen/http/openapi.yaml | grep -A 10 "securitySchemes"
生成完成后，gen/http/openapi.yaml 中应该能看到完整的 securitySchemes 定义（JWT Bearer），以及每个 path 下对应的 security 字段与 scope 声明——这正是 v3.28.0 修正的重点。
升级建议
- 大型项目优先升级：如果你的 Goa 设计文件超过 10 个 service 或生成耗时超过 20 秒，这个版本几乎是必升的。46→11 秒的差距在频繁迭代中会显著提升效率。
- 检查 OpenAPI 安全声明：升级后重新生成，对比新旧
openapi.yaml中securitySchemes和security字段。如果旧版本有遗漏，新版本会补上；如果你之前手动修补过，现在可以去掉那些补丁。 - Go 版本无硬性要求：v3.28.0 兼容 Go 1.25，但并不要求你必须用 1.25。在当前稳定版（1.23 / 1.24）下同样正常工作。
- 注意生成缓存：提速来自导入计算的全局化，不涉及缓存文件。首次生成和后续生成都会受益，无需额外配置。