hl-api-changelog/changelogs-v2/2026-09/17_7706_错误响应整数标识原样输出-修改接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	7706	错误响应中的整数标识不再出现千分位分隔	multiple	wx(GIT)	修改接口	deployed	verified	not_required					仅纠正 Result.message 中整数实参的渲染；code、HTTP 状态、响应结构和字段均不变，前端无需改代码。	2026-09-17	dev-v3

common：错误响应中的整数标识原样输出

服务: 全部依赖 hl-common-core 的后端服务 PR: #7748（dev-v3）；#7749（dev）已按 wx 最新范围决定关闭、不合入 Issue: #7706 日期: 2026-09-17 影响范围: 管理端、C 端及内部调用收到的业务错误 Result.message 文本

---

⚠️ 关键变化

无类型消息占位符收到整数 ID 时，不再按 locale 加千分位分隔符。完整 19 位 ID 现在保持原始十进制串，便于复制检索；code、HTTP 200 约定、Result 包络及字段结构均未改变。

---

一、背景

错误响应原来会把 2099459272533323777 显示为 2,099,459,272,533,323,777。运营复制带逗号的 ID 后无法检索。缺陷位于公共消息格式化层，因此修复覆盖所有依赖 hl-common-core 的错误响应；下方列出测试服真实验证接口。

---

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	旅行社公司详情	GET	/v3/admin/travel-agency/{id}	错误消息行为纠正	不存在的大整数 ID 在 594001 消息中原样输出

---

三、接口详情

1. 旅行社公司详情 GET /v3/admin/travel-agency/{id}

VO: Result<AgencyRespVO>

使用场景

管理端读取旅行社公司详情。传入不存在的公司 ID 时，接口仍按既有约定返回 HTTP 200 和业务码 594001；仅 message 中的整数渲染从带分组逗号改为原始十进制串。

入参

字段	位置	类型	必填	约束	说明
id	Path	Long	✅	正整数	旅行社公司 ID

出参 Result<AgencyRespVO>

字段	类型	说明
code	Integer	业务码；不存在时为 594001
message	String	业务消息；整数 ID 原样输出
data	AgencyRespVO / null	成功时为详情，不存在时为 null
traceId	String / null	链路标识，语义不变
success	Boolean	是否成功，语义不变

请求示例

GET /v3/admin/travel-agency/2099459272533323777
Authorization: Bearer ***

无请求体

响应示例

{
  "code": 594001,
  "message": "旅行社公司不存在(id=2099459272533323777)",
  "data": null,
  "traceId": null,
  "success": false
}

空数据 / 降级响应

本接口不存在独立空列表或降级包络；旅行社不存在时使用上面的 594001 错误响应，保持 HTTP 200。

错误响应

{
  "code": 594001,
  "message": "旅行社公司不存在(id=2099459272533323777)",
  "data": null,
  "traceId": null,
  "success": false
}

业务边界

• 鉴权、权限、HTTP 状态、错误码和数据结构均未修改。
• Byte、Short、Integer、Long、BigInteger、原子整型及长整型累加器进入无类型占位符时原样输出。
• BigDecimal、Double、Float 继续保留 JDK locale 行为；日期、时间和 choice 模板不变。
• 显式 number 元素收到非 Number（含 null）时按 String.valueOf 降级并记录 WARN，避免格式异常覆盖真实业务错误。

---

四、契约约束与正确调用方式

✅ 正确 / ❌ 错误 payload 对照

场景	调用方行为
✅ 判断业务结果	使用 code、success 和结构化 data
✅ 展示错误	将 message 作为展示文本，不依赖千分位形式
❌ 反解析标识	不从 message 提取或计算 ID；需要标识时使用请求参数或结构化字段

调用方注意事项

前端无需改动，也不得依赖旧的带逗号文本。既有 String.valueOf 绕行和显式 number 模板保持兼容。

---

六、边界行为

• 未登录仍由网关按既有规则拦截。
• 旅行社存在时成功响应内容不变。
• 旅行社不存在时仍为 HTTP 200、业务码 594001、data=null、success=false。
• 金额和浮点数格式不在本次修复范围内。

六.6、修改前后对比

字段级对比

字段	改前	改后
响应结构	code/message/data/traceId/success	不变
message 类型	String	String，不变

行为级对比

行为	改前	改后
无类型占位符 + 19 位 Long	2,099,459,272,533,323,777	2099459272533323777
BigDecimal/Double/Float	JDK locale 格式	不变
显式 number + Number	模板声明格式	不变
显式 number + 非 Number（含 null）	可能抛格式异常或静默保留占位符	String.valueOf 降级并记录 WARN

六.7、影响评估

• 是否破坏向后兼容: 否；响应结构不变，message 文本得到纠正。
• 前端是否必须同步上线: 否。
• 前端 workaround 清理点: 无；存量 String.valueOf 绕行保留。

七、不影响范围

• 仅影响: 业务错误消息里由无类型占位符渲染的整数实参，以及显式 number 收到非 Number 时的安全降级。
• 零影响:
  • Controller 路径、HTTP 方法、请求字段、响应字段及必填性
  • Feign 签名、DTO/VO/BO、错误码和 Result 包络
  • 金额、小数、日期、时间及 choice 模板的既有 JDK 语义
  • 数据库结构与存量数据

---

八、测试环境已验证

• PR #7748 合并提交：250365ba83c189189b3ede09d9e61891000a1280。

• gateway、user、resource、product-v2、order-v3、mp、fleet 均滚动到包含该提交的 335a853c52c4ec357518e080caa27cd8414e39ed，双实例健康。

• 网关 3/3 实测：HTTP 200、code 594001、完整 19 位 ID 无逗号。

• 双线聚焦契约矩阵全部通过；所有活动 consumer reactor 均已执行。非绿全量用例均在精确目标基线复现，与 #7706 无关。

  GET /v3/admin/travel-agency/2099459272533323777 → HTTP 200 → code=594001 → message=旅行社公司不存在(id=2099459272533323777) ✓

---

九、相关历史 PR

PR	Issue	说明	是否仍有效
#7748	#7706	dev-v3 公共格式化器修复并已部署	✅ 有效
#7749	#7706	原 dev 同步候选；2026-09-17 wx 明确今后代码只走 dev-v3，PR 已关闭未合入	❌ 不再适用

---

十、相关文档

• 关联 Issue: wx/HL#7706
• dev-v3 PR: wx/HL#7748
• dev PR: wx/HL#7749
• CODE_RULES PR: wx/hl-workflow#27

关联 / 联系人

链接

• Issue: #7706
• PR: #7748
• Merge commit: 250365ba83c189189b3ede09d9e61891000a1280

联系人

• 后端负责人: @wx