# Knife4j 接口文档按微服务多分组(#1404)

**日期**: 2026-04-25
**关联 PR**: #1405(Phase A) / #1406-#1410(Phase B 5 服务) / #1411(hotfix)
**工单**: [#1404](https://git.1814.love:8443/wx/HL/issues/1404)

---

## 🚨 前端 / 测试同事必看

### 接口文档地址不变
- 测试环境:https://api.test.1814.love:9443/doc.html(网关)
- 内网直连:http://192.168.100.236:8080/doc.html

### 左上角下拉菜单变化

**改造前**:35 个细粒度下拉项,如:
- `用户服务 - 管理员管理`
- `用户服务 - 角色管理`
- `用户服务 - 字典管理`
- `资源服务 - 酒店管理`
- `资源服务 - 服务项管理`
- ... (35 项,菜单冗长)

**改造后**:**5 个微服务级下拉**:
- 用户服务
- 资源服务
- 产品服务
- 订单服务
- 小程序 BFF

### 进入 group 后的 tag 列表

每个 tag 用 **4 类前缀**区分端类型,无需服务名前缀:
- `[admin] 模块名` - 管理端接口
- `[C端] 模块名` - 小程序端接口
- `[内部] 模块名` - internal/Feign 接口
- `[回调] 模块名` - 第三方平台事件回调(企微/公众号)

### 实例

**用户服务 group**(共 48 tag):
- `[C端] 公开字典` / `[C端] 出行人` / `[C端] 出行人OCR识别` / ...
- `[admin] Banner管理` / `[admin] 角色管理` / `[admin] 字典管理` / ...
- `[内部] 心愿` / `[内部] 联系我们` / `[内部] 部门用户` / ...
- `[回调] 公众号回调`

**订单服务 group**(共 51 tag):
- `[admin] 订单管理` / `[admin] 合同管理` / `[admin] 退款管理` / `[admin] 保险方案管理` / ...
- `[内部] 订单同步` / `[内部] 支付` / `[内部] 合同 Feign` / ...

## 改造规模(供 reviewer 参考)
- 7 PR(#1405-#1411)
- 274 Controller 文件 @Api(tags) 全量改名
- 5 个 Knife4jConfig.java 多 Docket 合并为单 Docket
- gateway/application.yml `knife4j.gateway.routes` 35 项 → 5 项

## 路由结构

| 服务 | 网关下拉名 | swagger group | 注册名 |
|------|-----------|--------------|--------|
| hl-user-service | 用户服务 | 用户服务 | hl-user-service |
| hl-resource-service | 资源服务 | 资源服务 | hl-resource-service |
| hl-product-service-v2 | 产品服务 | 产品服务 | hl-product-service-v2 |
| hl-order-service-v2 | 订单服务 | 订单服务 | **hl-order-service**(注:代码模块带 -v2 但 Nacos 注册名不带) |
| hl-mp-service | 小程序 BFF | 小程序 BFF | hl-mp-service |

## 实施踩坑

PR #1405 把订单服务 service-name 误写为 `hl-order-service-v2`(实际 Nacos 注册名是 `hl-order-service`,代码模块名带 -v2 是 maven module 名,但 spring.application.name 没带 -v2),导致 doc.html 订单 group 404。已在 #1411 hotfix 修正。

经验沉淀:Knife4j gateway routes / Feign client name 统一参考 Nacos 注册名(`spring.application.name`)而非 maven module 名,二者**可能不一致**。

## 不影响业务接口
本次仅改文档/分组,业务路径 / 鉴权 / 错误码 / Feign 调用全部不变。