goadesign/goa
GitHub: goadesign/goa
Goa 是一个 Go 语言的「设计优先」框架，通过 DSL 定义一次 API 即可自动生成 HTTP/gRPC 服务代码、客户端和文档，消除代码与文档的漂移。
Stars: 6092 | Forks: 585
# Goa - 设计优先，自信编码
## 概述
Goa 以其强大的设计优先方法，彻底改变了你在 Go 中构建 API 和微服务的方式。你无需编写样板代码，而是通过清晰、富有表现力的 DSL 来表达 API 的意图。随后，Goa 会自动生成可用于生产环境的代码、详尽的文档和客户端库——所有这些都与你的设计完美契合。
结果呢？大幅缩短开发时间，保持 API 的一致性，并彻底消除了困扰传统开发的文档与代码脱节的问题。
## 为什么选择 Goa？
传统的 API 开发常面临以下问题：
- **不一致性**：手动维护的文档很快就会与代码脱节
- **精力浪费**：编写重复的样板代码和传输层代码
- **痛苦的集成**：客户端包需要不断更新
- **设计后置**：文档在实现之后才添加，遗漏了关键细节
Goa 通过以下方式解决这些问题：
- 直接根据设计生成 30-50% 的代码库
- 确保设计、代码和文档之间完美契合
- 支持从单一设计生成多种传输协议（HTTP、gRPC 和 JSON-RPC）
- 在业务逻辑和传输细节之间保持清晰的分离
## 核心功能
- **富有表现力的设计语言**：使用清晰、类型安全的 DSL 定义 API，精准捕捉你的意图
- **全面的代码生成**：
- 强制执行设计的类型安全服务端接口
- 具备完善错误处理的客户端库
- 包含路由和编码的传输层适配器（HTTP/gRPC/JSON-RPC）
- 始终保持同步的 OpenAPI/Swagger 文档
- 用于测试服务的 CLI 工具
- **多协议支持**：从单一设计生成 HTTP REST、gRPC 和 JSON-RPC endpoint
- **整洁的架构**：业务逻辑与传输层关注点完全分离
- **企业级就绪**：支持身份验证、授权、CORS、日志记录等
- **全面的测试**：包含广泛的单元测试和集成测试套件，确保质量和可靠性
## 工作原理
```
┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐
│ Design API │────>│ Generate Code│────>│ Implement Business │
│ using DSL │ │ & Docs │ │ Logic │
└─────────────┘ └──────────────┘ └─────────────────────┘
```
1. **设计**：在 Goa 的 DSL 中表达 API 的意图
2. **生成**：运行 `goa gen` 创建服务端接口、客户端代码和文档
3. **实现**：专注于在生成的接口中编写业务逻辑
4. **演进**：随着 API 的演进，更新设计并重新生成代码
## 快速开始
```
# 安装 Goa
go install goa.design/goa/v3/cmd/goa@latest
# 创建一个新 module
mkdir hello && cd hello
go mod init hello
# 在 design/design.go 中定义 service
mkdir design
cat > design/design.go << EOF
package design
import . "goa.design/goa/v3/dsl"
var _ = Service("hello", func() {
Method("say_hello", func() {
Payload(func() {
Field(1, "name", String)
Required("name")
})
Result(String)
HTTP(func() {
GET("/hello/{name}")
})
})
})
EOF
# 生成代码
goa gen hello/design
goa example hello/design
# 构建并运行
go mod tidy
go run cmd/hello/*.go --http-port 8000
# 在另一个 terminal 中
curl http://localhost:8000/hello/world
```
上面的示例：
1. 定义了一个包含一个方法的简单 "hello" 服务
2. 生成服务端和客户端代码
3. 启动一个在服务端记录请求日志的服务（不显示任何客户端输出）
### JSON-RPC 替代方案
对于 JSON-RPC 服务，只需向 service 和 method 添加一个 `JSONRPC` 表达式：
```
var _ = Service("hello" , func() {
JSONRPC(func() {
Path("/jsonrpc")
})
Method("say_hello", func() {
Payload(func() {
Field(1, "name", String)
Required("name")
})
Result(String)
JSONRPC(func() {})
})
}
```
然后使用以下命令进行测试：
```
curl -X POST http://localhost:8000/jsonrpc \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"hello.say_hello","params":{"name":"world"},"id":"1"}'
```
## 文档
我们的文档网站 [goa.design](https://goa.design) 提供了详尽的指南和参考：
- **[简介](https://goa.design/docs/1-introduction/)**：了解 Goa 的理念和优势
- **[入门指南](https://goa.design/docs/2-getting-started/)**：循序渐进地构建你的第一个 Goa 服务
- **[教程](https://goa.design/docs/3-tutorials/)**：学习创建 REST API、gRPC 服务等
- **[核心概念](https://goa.design/docs/4-concepts/)**：掌握设计语言和架构
- **[实战指南](https://goa.design/docs/5-real-world/)**：遵循生产服务的最佳实践
- **[进阶主题](https://goa.design/docs/6-advanced/)**：探索高级功能和技巧
正在使用 AI 编程助手编写 Goa？请参阅 [`skills/`](skills/) 获取可重用的 Agent 技能，帮助 Agent 在应用程序仓库中遵循 Goa 的设计优先工作流。
## 实战示例
[示例仓库](https://github.com/goadesign/examples) 包含了完整的、可运行的示例，演示了：
- **Basic**：展示 Goa 核心概念的简单服务
- **Cellar**：一个更完整的 REST API 示例
- **Cookies**：HTTP cookie 管理
- **Encodings**：处理不同的内容类型
- **Error**：全面的错误处理策略
- **Files & Upload/Download**：文件处理功能
- **HTTP Status**：自定义状态码处理
- **Interceptors**：请求/响应处理中间件
- **Multipart**：处理 multipart 表单提交
- **Security**：身份验证和授权示例
- **Streaming**：实现流式 endpoint（HTTP、WebSocket、JSON-RPC SSE）
- **Tracing**：集成可观测性工具
- **TUS**：实现可恢复的文件上传
## 社区与支持
- 加入 Gophers Slack 的 [#goa](https://gophers.slack.com/messages/goa/) 频道
- 在 [GitHub Discussions](https://github.com/goadesign/goa/discussions) 提问
- 在 [Bluesky](https://goadesign.bsky.social) 上关注我们
- 在 [GitHub](https://github.com/goadesign/goa/issues) 上报告问题
- 使用 [Goa Guru](https://gurubase.io/g/goa) AI 助手寻找答案
- 订阅我们的 Substack“Design First”：[Design First](https://goadesign.substack.com/subscribe?params=%5Bobject%20Object%5D)
## 许可证
MIT 许可证 - 详情请参阅 [LICENSE](LICENSE)。
标签：API设计, Go, gRPC, Python工具, Ruby工具, Web框架, 代码生成, 日志审计, 渗透测试工具