API Changelog Bot 7c33a382bc docs(changelog): 在线文档恢复显示任务看板等接口分组(文档修复·非契约变更, PR#3597)

hl-user-service Swagger 扫描包过窄(com.hulalv.user.controller)漏扫 task/monitor/file
/callback/notification/wx 等子包,任务看板等整组接口在线文档不显示(接口本身一直可调)。
hl-mp-service 同类问题漏扫 complaint(投诉)。修复后两服务文档分组恢复显示,前端无需改码。

2026-06-08 14:50:44 +08:00

4.2 KiB

原始文件 永久链接 Blame 文件历史

在线接口文档恢复显示任务看板等接口分组 — 文档修复 — 管理后台兼小程序

变更类型：📄 文档修复（接口契约零变化，仅在线文档可见性恢复）端类型：管理后台（hl-user-service）+ 小程序（hl-mp-service）日期：2026-06-08 服务：hl-user-service、hl-mp-service PR：wx/HL#3597

⚠️ 关键说明（务必先看）

这些接口一直都存在，一直可以正常调用 —— 本次 没有新增、修改或删除任何接口，没有任何字段 / 路径 / 鉴权变化。
问题是在线接口文档（Knife4j / Swagger）的扫描包配置过窄，导致一批接口分组在文档页面不显示。前端如果只看在线文档，会误以为「任务看板等接口没有 / 被删了」。
本次修复后，这些分组在在线文档中恢复显示。前端无需改任何代码，刷新文档页面（建议 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	wx/HL#3597
Merge Commit	4976d3c8d
关联工单	无（在线文档展示问题，经排查为后端 Swagger 扫描配置）
后端负责人	wx

4.2 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape