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

**日期**: 2026-04-25
**状态**: 已上线测试服(dev `3082c367`)
**关联**: 后续优化于 [#1412](https://git.1814.love:8443/wx/HL/issues/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](https://git.1814.love:8443/wx/hl-api-changelog/raw/branch/main/changelogs/2026-04/2026-04-25_error-code-v2-full-migration.md)(段位表)
- 后端代码:`hl-*-service/src/main/java/com/hulalv/*/errorcode/*.java`

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

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