From cf45f2a26cf78eef7d292c642004ed4e1c6967ea Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sat, 25 Apr 2026 15:24:12 +0800 Subject: [PATCH] =?UTF-8?q?Knife4j=20=E6=8E=A5=E5=8F=A3=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E6=8C=89=E5=BE=AE=E6=9C=8D=E5=8A=A1=E5=A4=9A=E5=88=86=E7=BB=84?= =?UTF-8?q?=20(#1404=20/=20PR=20#1405-#1411)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...2026-04-25_knife4j-multi-group-refactor.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 changelogs/2026-04/2026-04-25_knife4j-multi-group-refactor.md diff --git a/changelogs/2026-04/2026-04-25_knife4j-multi-group-refactor.md b/changelogs/2026-04/2026-04-25_knife4j-multi-group-refactor.md new file mode 100644 index 0000000..7954c68 --- /dev/null +++ b/changelogs/2026-04/2026-04-25_knife4j-multi-group-refactor.md @@ -0,0 +1,75 @@ +# 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 调用全部不变。