7c33a382bc
hl-user-service Swagger 扫描包过窄(com.hulalv.user.controller)漏扫 task/monitor/file /callback/notification/wx 等子包,任务看板等整组接口在线文档不显示(接口本身一直可调)。 hl-mp-service 同类问题漏扫 complaint(投诉)。修复后两服务文档分组恢复显示,前端无需改码。
83 行
4.2 KiB
Markdown
83 行
4.2 KiB
Markdown
# 在线接口文档恢复显示任务看板等接口分组 — 文档修复 — 管理后台兼小程序
|
||
|
||
> 变更类型：📄 文档修复（接口契约零变化，仅在线文档可见性恢复）
|
||
> 端类型：管理后台（hl-user-service）+ 小程序（hl-mp-service）
|
||
> 日期：2026-06-08
|
||
> 服务：hl-user-service、hl-mp-service
|
||
> PR：https://git.1814.love:8443/wx/HL/pulls/3597
|
||
|
||
---
|
||
|
||
## ⚠️ 关键说明（务必先看）
|
||
|
||
1. **这些接口一直都存在，一直可以正常调用** —— 本次 **没有新增、修改或删除任何接口**，没有任何字段 / 路径 / 鉴权变化。
|
||
2. 问题是**在线接口文档（Knife4j / Swagger）的扫描包配置过窄**，导致一批接口分组在文档页面**不显示**。前端如果只看在线文档，会误以为「任务看板等接口没有 / 被删了」。
|
||
3. 本次修复后，这些分组在在线文档中**恢复显示**。前端**无需改任何代码**，刷新文档页面（建议 Ctrl+F5 强刷）即可看到。
|
||
|
||
---
|
||
|
||
## 1. 背景与根因
|
||
|
||
在线接口文档「用户服务」分组下原本看不到「任务看板管理」「任务管理」等接口。
|
||
|
||
根因：`hl-user-service` 的 Swagger 配置 `Knife4jConfig` 中，文档扫描包 `basePackage` 被限定为 `com.hulalv.user.controller` 这一个子包；而该服务的 Controller 实际散落在 `com.hulalv` 下的多个并列子包中（如任务看板在 `com.hulalv.task.controller`），这些子包全部落在扫描范围之外，于是整组接口在文档里不显示（但 Spring 照常注册、接口照常可调用）。
|
||
|
||
排查时一并核对了全部 6 个后端服务的 Swagger 配置，发现 `hl-mp-service` 存在同类问题：扫描包 `com.hulalv.mp.controller` 漏掉了 `com.hulalv.mp.complaint.controller`（投诉接口）。其余服务配置正确。
|
||
|
||
---
|
||
|
||
## 2. 恢复显示的接口分组清单
|
||
|
||
### 2.1 hl-user-service（在线文档分组「用户服务」）
|
||
|
||
修复后该分组 tag 由原先的「仅 user 子包」扩展到全部 86 个，下表为此前**被漏掉、现恢复显示**的代表性分组：
|
||
|
||
| 接口分组（tag） | 端 | 说明 |
|
||
|---|---|---|
|
||
| [admin] 任务看板管理 | 管理后台 | **本次反馈点**：看板 CRUD / 状态列 / 成员 |
|
||
| [admin] 任务管理 | 管理后台 | 任务 CRUD / 评论 / 提醒 |
|
||
| [admin] MySQL监控 / Redis监控 / RocketMQ监控 / 服务监控 | 管理后台 | 各中间件与服务监控 |
|
||
| [admin] 操作日志 / 登录日志 / 错误日志 / 消息通知日志 / 企微审批日志 | 管理后台 | 各类审计日志查询 |
|
||
| [admin] 微信内容安全-违规命中日志 | 管理后台 | 小程序内容安全命中记录 |
|
||
| [admin] 文件管理 / 通用OSS上传 | 管理后台 | 文件与对象存储 |
|
||
| [C端] 文件上传 | 小程序 | C 端文件上传 |
|
||
| [admin] 管理端站内信 / 站内信实时推送 / 通知中心管理 | 管理后台 | 站内信与通知中心 |
|
||
| [内部] 文件 / 日志接收 / 通知中心 / 登录日志 | 内部 Feign | 服务间内部接口 |
|
||
|
||
### 2.2 hl-mp-service（在线文档分组「小程序 BFF」）
|
||
|
||
| 接口分组（tag） | 端 | 说明 |
|
||
|---|---|---|
|
||
| [C端] 投诉 | 小程序 | 投诉提交 / 查询 |
|
||
|
||
---
|
||
|
||
## 3. 对前端的影响
|
||
|
||
| 项目 | 说明 |
|
||
|---|---|
|
||
| 是否需要改代码 | **否**。接口签名、路径、字段、鉴权全部不变 |
|
||
| 需要做什么 | 刷新在线文档页面（Ctrl + F5 强刷），即可在「用户服务」分组看到任务看板等接口；「小程序 BFF」分组看到投诉接口 |
|
||
| 是否影响线上调用 | 否。这些接口此前一直可正常调用，本次仅恢复文档可见性 |
|
||
|
||
---
|
||
|
||
## 4. 验证
|
||
|
||
部署测试服后，直接拉取两个服务的 Swagger JSON 确认（地面真相）：
|
||
|
||
- `hl-user-service` group「用户服务」：tag 总数 86，已含 `[admin] 任务看板管理`、`[admin] 任务管理` 等。
|
||
- `hl-mp-service` group「小程序 BFF」：tag 总数 51，已含 `[C端] 投诉`。
|
||
- 两服务均双实例 health UP（user 8081/8181，mp 8085/8185）。
|
||
|
||
---
|
||
|
||
## 5. 关联 / 联系人
|
||
|
||
| 项目 | 信息 |
|
||
|---|---|
|
||
| PR | https://git.1814.love:8443/wx/HL/pulls/3597 |
|
||
| Merge Commit | 4976d3c8d |
|
||
| 关联工单 | 无（在线文档展示问题，经排查为后端 Swagger 扫描配置） |
|
||
| 后端负责人 | wx |
|