221 行
7.3 KiB
Markdown
221 行
7.3 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "7706"
|
||
title: "错误响应中的整数标识不再出现千分位分隔"
|
||
consumer: "multiple"
|
||
author: "wx(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "not_required"
|
||
frontend_owner: ""
|
||
frontend_ref: ""
|
||
target_release: ""
|
||
verified_at: ""
|
||
status_note: "仅纠正 Result.message 中整数实参的渲染；code、HTTP 状态、响应结构和字段均不变，前端无需改代码。"
|
||
updated_at: "2026-09-17"
|
||
base: "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 | 是否成功，语义不变 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /v3/admin/travel-agency/2099459272533323777
|
||
Authorization: Bearer ***
|
||
|
||
无请求体
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 594001,
|
||
"message": "旅行社公司不存在(id=2099459272533323777)",
|
||
"data": null,
|
||
"traceId": null,
|
||
"success": false
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
本接口不存在独立空列表或降级包络；旅行社不存在时使用上面的 594001 错误响应，保持 HTTP 200。
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{
|
||
"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](https://git.1814.love:8443/wx/HL/issues/7706)
|
||
- dev-v3 PR: [wx/HL#7748](https://git.1814.love:8443/wx/HL/pulls/7748)
|
||
- dev PR: [wx/HL#7749](https://git.1814.love:8443/wx/HL/pulls/7749)
|
||
- CODE_RULES PR: [wx/hl-workflow#27](https://git.1814.love:8443/wx/hl-workflow/pulls/27)
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#7706](https://git.1814.love:8443/wx/HL/issues/7706)
|
||
- **PR**: [#7748](https://git.1814.love:8443/wx/HL/pulls/7748)
|
||
- **Merge commit**: [250365ba83c189189b3ede09d9e61891000a1280](https://git.1814.love:8443/wx/HL/commit/250365ba83c189189b3ede09d9e61891000a1280)
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @wx
|