接口元数据契约

接口元数据契约用于保证不同后端实现生成一致的 API 文档和接口描述。MineAdmin 推荐使用 OpenAPI/Swagger 作为公共表达形式，框架实现负责把自身注解、属性或配置转换为同一套元数据。

接口元数据不只服务于 Swagger UI。它同时影响前台类型生成、表单约束、权限按钮、调试工具和操作日志。因此，元数据应被视为“接口行为的一部分”，而不是代码写完后的附属说明。

必填信息

每个后台接口至少应描述以下信息：

信息	说明
路径与方法	接口路径、HTTP 方法和资源语义。
分组标签	所属业务模块，便于 Swagger UI 和前台工具识别。
认证要求	是否需要登录、Token 类型和安全方案。
权限标识	后台菜单、按钮或接口权限编码。
请求参数	路径参数、查询参数、请求体和文件字段。
响应结构	成功、失败、分页和业务异常的响应模型。

元数据来源

不同框架可以使用注解、属性、路由配置或独立描述文件生成 OpenAPI，但最终语义需要对齐。以当前 Hyperf 实现为例，元数据主要来自以下位置：

来源	契约语义
HTTP 方法注解	path、operationId、summary、tags、security。
Permission 属性	后台权限标识，应与菜单和按钮权限一致。
表单请求对象	请求体字段、必填字段、验证语义和字段说明。
Schema 类	响应字段、字段类型、嵌套对象和数组元素类型。
ResultResponse	普通接口统一响应结构。
PageResponse	列表接口分页响应结构。
全局 OpenAPI 配置	文档版本、服务地址、认证方案和外部文档入口。

如果某个实现无法把这些信息直接放进 OpenAPI 标准字段，应使用稳定的扩展字段承载 MineAdmin 语义，例如 x-permission、x-request-source 或等效字段。扩展字段名称一旦公开，应按接口契约维护。

路由操作元数据

每个接口操作应保持以下字段稳定：

字段	要求
operationId	在同一服务内唯一，作为客户端生成、接口变更识别和调试定位的稳定键。
summary	使用清晰的业务动作名称。当前实现也会用它记录操作日志，因此不要写成“接口一”“处理数据”等空泛描述。
tags	对应后台功能模块或资源归属，同一模块的接口应归入同一标签。
path	与后台路由契约一致，路径参数名称需要和方法参数、文档参数保持一致。
method	与真实 HTTP 方法一致，不能为了文档分组而改变语义。
security	准确声明接口是否需要访问令牌、刷新令牌或无需认证。

认证、权限和审计依赖的接口不应省略操作元数据。对于会改变系统状态的接口，summary 应能直接表达被记录的业务动作。

认证与权限元数据

MineAdmin 后台接口默认使用统一令牌体系。OpenAPI 中应声明全局安全方案，并在接口级别明确引用：

方案	说明
Bearer	HTTP Bearer Token，承载 JWT 访问令牌或刷新令牌。
ApiKey	Header 中的 token，用于兼容需要额外令牌的场景。

接口是否需要认证应以实际中间件和路由语义为准。登录接口不声明认证要求；退出、当前用户信息、普通后台资源和上传接口应声明认证要求；刷新令牌接口应明确它使用刷新令牌语义。

权限标识来自后端授权规则，也被前台按钮和菜单使用。接口元数据应保留权限编码，例如 permission:user:index、permission:user:save、dataCenter:attachment:upload。当 OpenAPI 标准字段无法表达权限时，需要通过扩展字段或生成器配置保留该值。

请求元数据

请求描述应覆盖参数位置、字段类型、必填状态和验证语义：

类型	要求
路径参数	在 path 中出现的参数必须声明为必填，并标注类型。
查询参数	列表、搜索、排序和分页参数应声明为查询参数或等效请求参数。
JSON 请求体	创建、更新、授权等接口应通过 request body 描述字段。
文件上传	使用 multipart/form-data，附件上传字段名固定为 file。
批量参数	ID 数组、权限数组、角色代码数组等应标注数组元素类型。

表单请求对象中的验证规则和文档必填字段应保持一致。例如规则中 required、required_with、sometimes 对应的必填/条件必填语义，需要在请求 schema 或字段说明里体现。字段白名单也需要一致，避免文档展示了后端不会接收的字段。

响应元数据

后台接口响应应统一描述为 Result 包装结构：

{
  "code": 200,
  "message": "成功",
  "data": {}
}

code 使用业务状态码，message 为业务消息，data 承载真实数据。接口元数据应描述 data 的具体结构，而不是只声明为泛型对象。

常见响应类型如下：

类型	data 结构
普通成功	对象、数组或空数组，按业务 schema 描述。
分页列表	至少包含 list 和 total；list 元素类型必须指向对应 Schema。
登录成功	包含 access_token、refresh_token 和 expire_at。
验证失败	使用统一错误响应，业务状态码为 422。
未认证/未授权	使用统一错误响应，业务状态码分别为 401、403。
禁用状态	使用统一错误响应，业务状态码为 423。

ResultCode 的枚举值应进入接口文档，至少覆盖成功、失败、未认证、未授权、未找到、方法不允许、不可接受、验证失败和禁用等场景。不同框架的异常处理可以不同，但对外元数据中的业务状态码语义需要保持一致。

Schema 约定

Schema 用于描述稳定的对外字段，不应直接暴露内部模型实现细节。

• Schema 名称应稳定，推荐使用资源名加 Schema 的形式。
• 字段名以最终 JSON 字段为准，例如 storage_mode、origin_name，不要让 PHP、JavaScript 或 ORM 的内部命名泄漏到契约中。
• 字段类型应使用 OpenAPI 可识别类型；数组字段需要声明元素类型。
• 嵌套关系应引用对应 Schema，避免把复杂对象退化成无结构的 array。
• 时间、枚举、状态值和文件字段应补充说明或示例。
• 请求 Schema 和响应 Schema 可以复用基础字段，但必须允许按场景过滤字段，避免创建接口、更新接口和返回对象混在一起。

分页与通用能力

列表接口应使用统一分页元数据：

项	约定
请求页码	page，默认 1。
每页数量	page_size，默认 10。
列表数据	data.list。
总数	data.total。

导入、导出、上传、批量删除、批量授权等通用能力应使用固定的命名和结构。比如附件上传的 request body 必须能看出 file 是文件字段，批量授权用户角色的 role_codes 必须标注为字符串数组。

元数据一致性

• 同一接口在不同框架实现中应生成一致的路径、方法、标签和响应模型。
• 字段名称、类型、必填状态和示例值应与真实接口保持一致。
• 权限标识应和菜单/按钮配置共用同一套编码。
• 分页、导入导出、文件上传等通用能力应使用统一描述方式。
• 操作名称、权限编码和响应 Schema 的变更应被视为兼容性变更。
• 对已公开字段进行重命名或删除时，应先通过废弃说明、版本说明或新增字段过渡。

示例

以下示例展示接口元数据应表达的核心语义，不限定具体框架写法：

paths:
  /admin/user/list:
    get:
      operationId: userList
      summary: 用户列表
      tags:
        - 用户管理
      security:
        - Bearer: []
          ApiKey: []
      x-permission: permission:user:index
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: page_size
          in: query
          schema:
            type: integer
            default: 10
      responses:
        "200":
          description: 成功

与前台模板的关系

前台模板可以基于接口元数据生成请求类型、表单约束或调试文档。因此接口元数据不是单纯的说明文档，而是前后端协作的稳定契约。

前台依赖接口元数据时，通常会读取以下信息：

• 根据 operationId 和路径生成请求方法。
• 根据 request body 和参数 schema 推导表单字段与类型。
• 根据响应 schema 推导列表、详情和选择器的数据类型。
• 根据权限标识控制按钮、菜单和页面能力。
• 根据认证声明决定是否附加访问令牌或刷新令牌。

框架实现

Hyperf 当前通过 MineAdmin Swagger 注解封装生成接口元数据，具体用法见 Hyperf 路由与 API 文档。