API 目录 (/api)

相关源文件

• README.md
• README_fr.md
• api/README.md

目的与范围

/api 目录作为存储 API 规范、接口定义和协议文档的集中位置。此目录专门用于存放项目服务接口的正式描述，而非实现代码本身。有关 API 端点实现的信息，请参阅 命令目录 (/cmd) 和 内部目录 (/internal)。

来源：README.md100-104

内容和组织

/api 目录应包含：

• OpenAPI/Swagger 规范文件
• Protocol Buffer 定义（.proto 文件）
• JSON Schema 文件
• GraphQL 模式定义
• API 文档和接口契约
• RPC 服务定义

该目录是项目公共 API 表面的一部分，这意味着这些定义代表了客户端可以依赖的官方接口。

来源：README.md102 api/README.md3

与其他组件的关系

/api 目录定义了由 /internal、/pkg 和 /cmd 目录中的代码实现的接口。这些定义充当了您的服务与其客户端之间的契约，无论客户端是外部应用程序、生成的 SDK 还是文档工具。

来源：README.md102-104

目录结构

/api 目录可以按 API 版本、服务边界或两者进行组织。以下是一个典型的组织模式：

此结构允许清晰的 API 版本控制和领域分离，从而更容易随着时间的推移管理 API 的演进。

来源：api/README.md1-9

常见文件类型和格式

文件类型	目的	典型扩展名
OpenAPI/Swagger	RESTful API 定义	.yaml, .json
Protocol Buffers	gRPC 服务定义	.proto
JSON 模式	数据结构验证	.schema.json
GraphQL	API 查询语言模式	.graphql
RAML	RESTful API 建模语言	.raml
API Blueprint	API 文档	.apib

与代码生成的集成

/api 目录中存储的 API 定义通常是生成以下内容的源头：

1. 服务器端请求验证代码
2. 多种语言的客户端 SDK
3. API 文档
4. 用于测试的 Mock 服务

诸如 protoc、swagger-codegen 等工具可以将您的 API 定义转换为可用的代码，从而提高生产力并确保文档与实现之间的一致性。

来源：api/README.md3-4

实际应用示例

/api 目录模式在许多著名的 Go 项目中都有使用：

1. Kubernetes - 使用 /api 目录来定义其资源类型和版本化 API。
2. Docker/Moby - 存储 Docker Engine API 的 API 规范。

这些项目展示了 API 定义如何与实现分离，同时保持接口和代码之间的清晰关系。

来源：api/README.md7-8

最佳实践

1. 版本化您的 API - 使用目录结构清晰地指示 API 版本。
2. 保持定义格式无关 - 关注逻辑 API，而不是特定的传输协议。
3. 维护向后兼容性 - 一旦发布，API 定义应遵循正确的弃用周期。
4. 广泛记录 - 在 API 定义中包含示例、描述和约束。
5. 引用数据模型 - 使用共享模式来确保跨端点的 Re一致性。

总结

/api 目录是标准 Go 项目布局的关键组成部分，它作为 API 定义和规范的中央存储库。它代表了您的服务向客户端提供的公共契约，并且应仔细维护，以确保向后兼容性和清晰的文档。

作为公共 API 表面的一部分，一旦发布，其内容应被视为稳定的，并为任何更改应用正确的版本控制策略。