hl-api-changelog/changelogs/2026-04/2026-04-25_swagger-error-code-narrow.md

Swagger 业务码精简显示(#1417 / PR #1418-#1420)

日期: 2026-04-25 状态: 已上线测试服(dev 3082c367) 关联: 后续优化于 #1412

---

改造前(#1412 完成时)

每个接口的「响应状态」区显示 193 行(4 HTTP + 189 业务码全集)— 太冗余。

改造后(#1420 上线)

每个接口显示 21 行:

• 4 HTTP 标准(200 / 401 / 403 / 404)
• 13 通用业务码:
  • common 段(100xxx):SYSTEM_ERROR / INVALID_PARAM / DATA_NOT_FOUND / OPERATION_NOT_ALLOWED / RATE_LIMITED / IDEMPOTENT_REJECTED / FEIGN_EMPTY_DATA / FEIGN_CALL_FAILED
  • auth 段(110xxx):UNAUTHENTICATED / TOKEN_EXPIRED / TOKEN_INVALID / PERMISSION_DENIED / RESOURCE_NOT_FOUND
  • system 段(900xxx):RATE_LIMITED / CIRCUIT_BROKEN / SERVICE_DEGRADED / GATEWAY_ERROR
• 0 ~ N 个 controller 字节码直接引用的业务码(由 ASM 启动时扫描)

实现路径(踩坑)

1. PR #1418:按服务模块过滤,但 user-service 自己注册的码就 189,过滤无效
2. PR #1419:ASM 扫 controller 字节码 + fallback module 全集,99% controller 不直接 throw 走 fallback 仍 189
3. PR #1420(终版):删除 fallback,只显示通用 + ASM 扫到的引用

完整业务码全集查询

• 后端启动日志:ErrorCodeRegistry scan complete, totalCodes=N
• 前端文档:errorcode-catalog(段位表)
• 后端代码:hl-*-service/src/main/java/com/hulalv/*/errorcode/*.java

前端处理建议

• HTTP 401 / 403 / 404 走拦截器分支(已有,不变)
• 通用码 100xxx / 110xxx / 900xxx 提示规则统一(如 100501 RATE_LIMITED 显示"操作过于频繁")
• 业务码用 message 弹 toast,不必为每个 code 写分支

不影响

所有业务接口/响应数据结构/前端调用约定完全不变,只是文档展示精简。