REST API网关传递调用用户ID：请求头还是查询参数？

核心结论 #

优先选择请求头传递调用用户ID，这是行业内更符合开发者习惯的做法。

具体原因 #

1. 语义清晰，区分上下文与业务参数 #

• 调用用户ID是请求的身份上下文信息（用于全量请求的权限校验），不属于业务核心参数；而目标用户ID是业务参数（比如groups/{abc}/add-user接口中要添加的用户），放在路径、请求体或业务查询参数里更合理。
• 用请求头传递上下文信息，能让开发者快速区分：哪些是业务相关参数，哪些是请求环境/身份类的元数据，从根源避免混淆。

2. 贴合REST设计规范 #

REST架构中，查询参数用于业务过滤、排序或核心参数传递，请求头则专门承载元数据（如身份信息、内容类型、认证凭据等）。调用用户ID属于身份元数据范畴，放在请求头更符合REST的设计理念。

3. 避免URL冗余与日志污染 #

• 如果用查询参数传递，每个请求的URL都会带上calling-user-id=xxx，不仅冗余，还会让用户ID出现在各类监控、日志的URL记录中（虽非敏感信息，但没必要暴露在URL层面）。
• 请求头信息可按需配置是否记录到日志，灵活性更高。

4. 与JWT认证流程自然衔接 #

你的场景里调用用户ID来自签名JWT，API网关验证后提取。JWT本身通常放在Authorization请求头中，网关提取用户ID后用专属请求头（比如X-Calling-User-ID）传递给后端，整个流程连贯，符合开发者对身份信息传递的普遍认知。

补充建议 #

• 请求头命名建议用行业通用前缀，比如X-Calling-User-ID，比user-context更直观，其他开发者一眼就能理解这是调用者的用户ID。
• 目标用户的混淆ID继续放在业务参数位置（路径、查询参数或请求体），保持业务语义的清晰性。

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