---
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