hl-api-changelog/changelogs-v2/2026-08/26_6409_行政区划响应ID固定为字符串-修改接口-管理后台.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	6409	行政区划响应 ID 固定为字符串	admin	lc(GIT)	修改接口	deployed	verified	not_required					PR #6412 已合并 dev-v3；hl-user-service 已以提交 4b31612a 部署 TEST，create、children、path 经真实 Gateway 验证全部 Long ID 固定为 JSON string，空层级保持 null。	2026-08-26	dev-v3

行政区划响应 ID 固定为字符串

行政区划创建、单级联动和父链回显接口中的 Long ID 现在始终按 JSON 字符串返回，避免小整数因全局安全整数规则被输出为 JSON number。请求参数、权限、业务校验和错误码不变。

变更接口

方法	路径	响应变化
POST	/admin/region	成功响应 data 从 JSON number 固定为 string
GET	/admin/region/children	parentId、defaultId、items[].id、items[].parentId 固定为 string；空值保持 null
GET	/admin/region/{id}/path	selectedId、provinceId、prefectureId、countyId 及 path 节点 ID 固定为 string；缺失层级保持 null

更新接口 PUT /admin/region/{id} 的请求和响应不变。所有请求路径、Query/Path 参数仍按原 Long 语义解析。

兼容性与错误语义

• 这是已发布接口 JSON 类型的契约修正，不新增字段，也不改变字段名称。
• 行政区划 Redis 缓存可同时反序列化旧 JSON number 与新 JSON string，滚动部署期间兼容。
• 根层 parentId、无默认节点的 defaultId 和父链中不存在的层级继续返回 null，不会变成字符串 "null"。
• 未认证请求继续返回业务码 401；非法正整数参数、缺失节点和非法节点类型继续使用既有错误语义，失败路径零业务写入。
• 无数据库 migration、配置、Gateway、MQ、缓存键或跨服务契约变更；无需修改前端源码，调用方按既定字符串 ID 契约消费即可。
• 统一响应可能以 HTTP 200 承载业务失败，客户端必须同时检查 code、success、message 和 data。

TEST 验证证据

• PR #6412 合并提交为 8494028aa2dfbb4e39147c09695898d247045d4c；TEST 目标提交 4b31612aeba5c0d3ac690cc6af15b66290bd8b48 包含该合并提交。
• Deploy Panel API 任务 b10dd2ed 成功执行 /opt/hulalv/scripts/deploy-backend.sh；User 的 8081、8181 双实例和 Nacos 两个 healthy/enabled 实例通过，任务期 9 个可验证采样均有可用实例，0 个故障采样。
• 真实 TEST 管理员经 Gateway 验证 create、children、path：创建 ID、联动列表 ID、父链 ID 和对应 Redis 缓存 ID 均为字符串，根节点和缺失层级空值保持 null。
• 未认证请求返回 401；非法父节点、缺失节点、空创建和旧非法节点类型均按既有错误返回，并确认失败路径零写入。
• 成功创建和 CAS 更新后，精确删除本次创建的 1 行；数据库总量恢复且测试命名空间为 0。4 个相关 Redis key 按基线值及绝对过期时间恢复，验收会话已注销；操作审计按系统约定保留。
• 本地验证：Controller/Cache 定向 22 项通过；User 全量 3644 项通过、0 失败、0 错误，8 项条件跳过；hl-verify 与 git diff --check 通过。

撤回

1. 从最新 dev-v3 创建独立回退分支，执行 git revert -m 1 --no-edit 8494028aa2dfbb4e39147c09695898d247045d4c，经评审 PR 合入；不要回退后续无关提交。
2. 通过 Deploy Panel API 对回退目标执行新鲜预检和显式部署 hl-user-service，复核双实例、Nacos、日志和精确提交。
3. 本修复无数据库、配置或 MQ 变更，不执行 DDL、DML 或消息补偿。缓存新旧表示均可读取，通常无需清理；确需强制恢复旧表示时，仅在停止行政区划刷新后精确处理 hl:user:region:v1: 命名空间并由回退版本预热。
4. 撤回前确认调用方可重新接受 JSON number ID；撤回后经 Gateway 复测 create、children、path、空层级、未认证和失败零写入。

关联 / 联系人

• Issue: #6409
• PR: #6412
• 合并提交: 8494028aa
• 后端负责人: @lc