📚 课程目录第3章刷新请求构造

3. 刷新请求构造：HTTP POST 请求的必需参数

刷新令牌（Refresh Token）流程的核心在于客户端向授权服务器发起一次 HTTP POST 请求，以换取新的访问令牌（Access Token）。该请求的构造必须严格遵循 RFC 6749 规范，缺失或错误的参数将直接导致授权服务器返回错误响应。本节将详细拆解四个必需参数的含义、格式及常见构造误区。

3.1 请求端点与 Content-Type

刷新请求的目标端点是授权服务器的 令牌端点（Token Endpoint），通常与获取访问令牌的端点相同。请求体必须采用 application/x-www-form-urlencoded 格式进行编码，并使用 HTTP POST 方法。

  关键约束： 授权服务器通常拒绝 GET 请求或 Content-Type 为 application/json 的 POST 请求。务必在请求头中显式设置 Content-Type: application/x-www-form-urlencoded。

3.2 必需参数清单与说明

下表列出了刷新请求中必须携带的四个参数，以及它们在 OAuth 2.0 规范中的定义与约束：

参数名	是否必需	值类型	说明
`grant_type`	是	字符串	固定值为 `refresh_token`，用于告知授权服务器本次请求属于刷新令牌流程。
`refresh_token`	是	字符串	客户端先前从授权服务器获取的刷新令牌值。该值必须保持原样传递，不可进行 URL 编码之外的二次转义。
`client_id`	是	字符串	客户端注册时获得的唯一标识符。用于授权服务器识别请求来源。
`client_secret`	是	字符串	客户端注册时获得的密钥。用于验证客户端身份。对于机密客户端（Confidential Client）此参数为强制项。

注意： 对于公开客户端（Public Client，如纯浏览器端 SPA 应用），client_secret 可能不被要求。但在大多数服务端实现中，刷新令牌属于高权限操作，授权服务器通常强制要求提供 client_secret 以增强安全性。请以授权服务器的文档为准。

3.3 请求构造示例

以下是一个符合规范的 HTTP POST 请求示例，展示了参数在请求体中的实际编码形式：

POST /oauth/token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

grant_type=refresh_token
&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
&client_id=s6BhdRkqt3
&client_secret=GX1fBat3bV

在上述示例中：

grant_type 被设置为 refresh_token，明确标识流程类型。
refresh_token 携带了之前颁发的令牌值 tGzv3JOkF0XG5Qx2TlKWIA。
client_id 和 client_secret 用于客户端身份认证。注意，部分实现允许将 client_id 和 client_secret 通过 HTTP Basic 认证头传递，但将其放入请求体是更常见且兼容性更好的做法。

3.4 参数构造的常见错误与断言

在故障定位中，以下错误是导致刷新请求失败的高频原因。开发者应重点检查这些断言点：

grant_type 拼写错误：refresh_token 中的下划线位置、大小写必须完全匹配。常见错误包括 refreshtoken、refresh-token 或 RefreshToken。
refresh_token 值被截断或转义：刷新令牌通常为长字符串，在 URL 编码过程中可能被错误截断。建议在发送前打印原始令牌长度并与服务器颁发时的长度进行比对。
client_id 与 client_secret 不匹配：授权服务器会校验 client_id 与 client_secret 的对应关系。如果客户端在注册后重新生成了密钥，旧密钥将立即失效。
重复参数：请求体中不应出现同名参数两次。某些 HTTP 客户端库在拼接参数时可能意外重复，导致服务器解析异常。

3.5 刷新请求构造流程（SVG）

下图展示了从客户端构造请求到授权服务器接收并解析的完整数据流，重点标注了四个必需参数的传递路径：

3.6 参数缺失时的错误响应

当必需参数缺失或格式错误时，授权服务器将返回 HTTP 400 Bad Request 状态码，并在响应体中携带错误信息。下表列出了常见缺失场景对应的错误码：

缺失参数	错误码 (error)	错误描述 (error_description)
`grant_type`	`unsupported_grant_type`	The authorization grant type is not supported by the authorization server.
`refresh_token`	`invalid_request`	The request is missing a required parameter: refresh_token.
`client_id`	`invalid_client`	Client authentication failed (e.g., unknown client, no client authentication included).
`client_secret`	`invalid_client`	Client authentication failed due to missing or invalid client_secret.

调试建议： 在开发阶段，建议使用 API 调试工具（如 Postman 或 cURL）手动构造刷新请求，逐一移除参数以观察服务器返回的错误码。这有助于快速确认授权服务器的参数校验逻辑，并为后续自动化集成提供断言依据。