ouyangxq
19745e46c1
18 个服务与公共模块重复复制的 314 字符数据库访问约束改为指向后端根唯一定义，并给索引门禁增加防退化校验。 - 18 处重复段落合并为一句指针，规则正文只在后端根 AGENTS.md 维护 - 门禁新增路由表行宽上限（根/Admin/Client/后端根/海外 PDA），防止业务规则重新回流表格 - 同步包含此前未提交的链接与锚点、表格存在性校验 - 仅索引文档与门禁脚本，未改动业务代码
30 lines
2.1 KiB
Markdown
30 lines
2.1 KiB
Markdown
# Common OpenAPI 模块指引
|
|
|
|
## 数据库访问与中文注释约束
|
|
|
|
- 强制继承 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则；该节是分层、SQL 执行和方法/核心逻辑中文注释的唯一维护处，本模块不另设例外。
|
|
|
|
## 职责边界
|
|
|
|
- 为 Spring MVC 服务提供 SpringDoc/OpenAPI 自动配置和统一文档元数据。
|
|
- 不在这里维护具体业务接口契约；服务专属 OpenAPI 文件留在对应服务资源目录。
|
|
|
|
## 快速索引
|
|
|
|
| 功能 | 入口 |
|
|
|---|---|
|
|
| 自动配置 | `src/main/java/com/baiyue/common/openapi/BaiyueOpenApiAutoConfiguration.java` |
|
|
| `baiyue.openapi` 配置项 | `src/main/java/com/baiyue/common/openapi/OpenApiProperties.java` |
|
|
| 自动配置注册 | `src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` |
|
|
| 长整型 OpenAPI 字符串契约 | `src/main/java/com/baiyue/common/openapi/BaiyueOpenApiAutoConfiguration.java` |
|
|
| PDA OpenAPI 分组 | `src/main/java/com/baiyue/common/openapi/BaiyueOpenApiAutoConfiguration.java` 的 `pda` GroupedOpenApi；固定匹配 `/api/pda/**`，合同测试 `src/test/java/com/baiyue/common/openapi/PdaOpenApiGroupContractTest.java` |
|
|
|
|
## 修改与验证
|
|
|
|
- 调整分组、标题或安全方案时检查所有 MVC 服务的 Swagger 输出；Gateway 的 WebFlux 聚合配置在 `gateway/`。
|
|
- PDA Controller 必须进入独立 `pda` 分组；新增或改名 `/api/pda/**` 路径时同步检查分组合同和目标服务 OpenAPI，不得混入平台或商户分组。
|
|
- 普通业务成功和失败在 OpenAPI 中统一描述为 HTTP 200，并提示调用方检查 body `code`；只为 Security、协议、基础设施、Warehouse 503、Audit 202 和 Event Bridge 内部鉴权等真实状态边界声明非 200 响应。
|
|
- 配置项变化直接同步代码、全部消费者和 Nacos 模板；当前正式配置不保留旧配置键兼容。若已有不可变外部配置契约，先单独定义升级规则。
|
|
- 从父目录运行 `mvn -pl common-openapi -am test`。
|
|
- 所有 Java `Long/long` 在 OpenAPI 中统一声明为字符串，与 HTTP JSON 序列化保持一致。
|