REST API 本地化实现方案选择：参数放请求头还是请求体？

API本地化参数传递方案选择建议 #

优先选择方案1（HTTP请求头传递本地化信息），你的原有判断逻辑完全符合HTTP协议设计规范和生产API迭代的最佳实践，以下是补充的验证依据和落地注意事项：

方案1（请求头传递）的核心优势 #

• 零侵入兼容现有生产API：不需要修改已有的请求体结构、参数校验逻辑和API契约，不会影响存量用户的正常调用，上线风险极低，无需推动存量调用方做适配改造
• 符合HTTP语义规范：本地化配置属于请求元数据，和Accept-Language、Content-Type等标准内容协商参数的定位完全一致，放在请求头中符合HTTP协议的设计逻辑，所有网关、代理、日志采集组件都可以直接识别、传递、打印该参数，排查问题时不需要解析请求体即可快速获取配置信息
• 便于架构层统一复用：如果后续其他API也需要支持本地化能力，不需要逐个修改每个接口的请求体定义，只需要在网关层面统一拦截处理该请求头即可，还可以基于该头实现全局的默认值兜底、单位统一转换等通用逻辑
• 接口职责边界清晰：请求体仅承载业务相关参数，横切类的元数据和业务逻辑完全解耦，后续调整本地化参数结构时也不会污染业务参数契约

方案2（请求体传递）的适用场景 #

仅当存在以下特殊限制时，才考虑选择方案2：

• 本地化参数需要和业务请求参数做强绑定校验，比如不同业务场景下允许的单位规则存在差异，必须和业务参数同步校验
• 需要支持单请求内多套本地化配置的复杂场景，比如同一个请求需要同时返回千米、英里两种单位的计算结果，这类场景请求头无法灵活承载
• 调用方存在特殊限制无法传递自定义请求头，比如老旧浏览器跨域场景、受限IoT设备不支持自定义头，这种情况只能妥协放到请求体中

方案1落地注意事项 #

• 自定义请求头建议遵循业界命名规范，增加X-前缀，比如命名为X-Localization，避免和标准HTTP头冲突
• 如果头的值采用JSON结构，建议做Base64编码，避免特殊字符导致解析失败，示例：X-Localization: eyJkaXN0YW5jZVVuaXQiOiAia20ifQ==
• 需要配置默认值兜底，调用方未传递该头时默认使用服务端预设的单位规则，避免无意义的报错
• 如果接口支持跨域调用，需要在CORS配置中将X-Localization添加到Access-Control-Allow-Headers列表中，否则浏览器会拦截该自定义头

内容的提问来源于stack exchange，提问作者Sagar