在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

golang-standards/project-layout

菜单

接口目录

相关源文件

目的与范围

本文档解释了标准 Go 项目布局中接口目录的用途和组织结构。接口目录是 Go 项目的组成部分，它们定义了应用程序如何与外部世界进行通信——无论是机器交互还是人工交互。

本页涵盖了 /api 和 /web 目录，它们分别是服务和 Web 应用程序的主要接口点。有关 /cmd、/internal 和 /pkg 等核心目录的信息，请参阅 核心目录结构。

接口目录概述

接口目录包含定义和资源，这些构成了应用程序的面向外部的方面。它们在应用程序的实现（位于 /internal 和 /pkg）与外部实体如何与之交互之间建立了清晰的边界。

图示：Go 项目结构中的接口目录

来源：README.md100-110

API 目录 (/api)

The /api 目录包含描述应用程序 API 接口的定义和规范。这些定义充当服务与其使用者之间的契约。

/api 目录的内容

The /api 目录通常包含

  1. OpenAPI/Swagger 规范：REST API 的正式定义
  2. Protocol Buffer 定义：用于 gRPC 服务
  3. JSON Schema 文件：用于验证请求/响应负载
  4. GraphQL schema：用于 GraphQL API 定义

图示：API 目录组件及关系

来源：README.md100-104

使用模式

The API directory serves several important functions in a Go project

  1. 契约定义：提供 API 契约的清晰文档
  2. 代码生成：API 定义通常驱动服务器和客户端的代码生成
  3. 版本控制：API 规范包含版本控制信息
  4. 文档：作为 API 文档的权威来源

最佳实践

  • 将每个 API 版本保留在其自己的子目录中（例如，/api/v1，/api/v2）
  • 存储源规范（如 OpenAPI YAML）和任何生成的输出
  • 将示例包含在规范旁边
  • 确保所有 API 定义都有清晰的文档
  • 在适用时使用 Swagger UI 等工具进行交互式文档

Web 目录 (/web)

The /web 目录包含与 Web 接口相关的组件，包括静态资源、模板和单页应用程序 (SPA)。此目录侧重于通过浏览器进行的与人的交互，而不是机器到机器的通信。

/web 目录的内容

The /web 目录通常包含

  1. 静态资源：CSS、JavaScript、图像
  2. 服务器端模板：Go 模板、视图
  3. 单页应用程序：React、Vue、Angular 应用程序
  4. Web 组件：可重用的 UI 组件
  5. Web 特定配置：Web 服务器配置、路由定义

图示：Web 目录组件及关系

来源：README.md108-110

使用模式

The web directory serves several important functions

  1. 资产组织：为 Web 资产提供结构化的位置
  2. 关注点分离：将 UI 组件与后端逻辑分开
  3. 构建管道集成：通常与前端构建工具集成
  4. 开发工作流：支持前端和后端开发工作流

最佳实践

  • 按类型组织静态资源（CSS、JS、图像）
  • 使用构建过程优化生产环境的资源
  • 尽可能将模板保存在靠近其处理程序的位置
  • 考虑为主要 UI 部分使用子文件夹
  • 包含一个 README 文件，解释前端架构和构建过程

与核心组件集成

两个接口目录都与应用程序的核心组件密切交互。理解这些关系对于维护结构良好的 Go 项目至关重要。

图示：接口目录与核心组件的集成

来源：README.md58-110

实施流程

  1. API 驱动开发:

    • 在 /api 中定义 API 规范
    • 在 /internal 中实现处理程序
    • 在 /pkg 中公开可重用组件
    • 在 /cmd 中创建应用程序入口点

  2. Web 驱动开发:

    • 在 /web 中设计 Web 界面
    • 在 /internal 中实现处理程序
    • 在 /web/templates 中创建 HTML 模板
    • 连接到 /internal 中的业务逻辑

额外考量

公开与私有接口

组织接口目录时，请考虑

  1. 公共 API：供外部使用的 API 应具有清晰的规范和文档
  2. 内部 API：仅在您的应用程序或组织边界内使用的 API
  3. Web 界面：考虑公共与管理界面及其安全要求

版本控制

接口目录应包含版本控制策略

接口类型版本控制方法示例
REST APIURL 路径组件/api/v1/users
gRPC API包命名proto 文件中的 package v1
Web 组件目录结构/web/v2/components
GraphQL APISchema 版本控制类型后缀或单独的 schema

测试

接口目录应附带全面的测试

  1. API 测试：根据实现验证 API 规范
  2. Web 测试：测试前端组件和与后端的集成
  3. 契约测试：确保消费者和提供者遵守定义的契约

总结

接口目录（/api 和 /web）构成了 Go 应用程序与其外部使用者之间的边界。通过正确组织这些目录，您可以在接口定义与其实现之间建立清晰的隔离，从而实现更易于维护和理解的代码库。

在构建公开 API 或 Web 界面的 Go 应用程序时，这些目录为定义他人如何与您的应用程序交互的规范、资源和模板提供了结构化的位置。

来源：README.md100-110