refactor(openapi): 客户端签名统一为字典序+&拼接风格

- BuildOpenV1Sign 改为 app_key/body_sha256/method/nonce/path/timestamp
  按 ASCII 字典序用 & 拼接,与上游 BuildSignString 风格一致
- body 以 SHA256 摘要参与签名,避免大 body 与特殊字符问题
- 同步更新中间件调用点、测试用例与前端鉴权文档
This commit is contained in:
yml2213
2026-07-30 15:53:09 +08:00
parent 4165fc4d01
commit 881ef40fb7
3 changed files with 33 additions and 29 deletions
+17 -17
View File
@@ -125,33 +125,32 @@ function AuthTab() {
<Card size="small" title="签名算法">
<Descriptions size="small" column={1} bordered>
<Descriptions.Item label="签名内容">
<Text code>{'timestamp\nnonce\nMETHOD\npath\nsha256(body)'}</Text>
<Descriptions.Item label="参与参数">
<Text code>app_key</Text>、<Text code>body_sha256</Text>、<Text code>method</Text>、<Text code>nonce</Text>、<Text code>path</Text>、<Text code>timestamp</Text>
</Descriptions.Item>
<Descriptions.Item label="拼接方式">按固定顺序,用换行符 <Text code>\n</Text> 拼接</Descriptions.Item>
<Descriptions.Item label="METHOD">大写,如 GET / POST</Descriptions.Item>
<Descriptions.Item label="拼接方式">参数按 ASCII 字典序,用 <Text code>&</Text> 拼成 <Text code>k1=v1&k2=v2&...</Text></Descriptions.Item>
<Descriptions.Item label="排序后顺序">
<Text code>app_key, body_sha256, method, nonce, path, timestamp</Text>
</Descriptions.Item>
<Descriptions.Item label="method">大写,如 GET / POST</Descriptions.Item>
<Descriptions.Item label="path">仅 URL.Path,不含域名和 query</Descriptions.Item>
<Descriptions.Item label="body">GET 为空字节;POST 必须与实际发送 body 完全一致</Descriptions.Item>
<Descriptions.Item label="body_sha256">
<Text code>SHA256(原始 body 字节)</Text> 的十六进制小写;GET 用空 body 的摘要
</Descriptions.Item>
<Descriptions.Item label="value">原样拼接,不做 URL encode</Descriptions.Item>
<Descriptions.Item label="X-Sign">
<Text code>hex( HMAC-SHA256( app_secret, 签名内容 ) )</Text>,小写十六进制
<Text code>hex( HMAC-SHA256( app_secret, 签名串 ) )</Text>,小写十六进制
</Descriptions.Item>
</Descriptions>
</Card>
<Card size="small" title="签名示例(GET,body 为空)">
<pre style={preStyle}>{`timestamp
nonce
GET
/api/client/v1/products
sha256("") = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`}</pre>
<pre style={preStyle}>{`app_key=ak_xxx&body_sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855&method=GET&nonce=a1b2c3d4e5f67890&path=/api/client/v1/products&timestamp=1721450000`}</pre>
</Card>
<Card size="small" title="签名示例(POST,body 非空)">
<pre style={preStyle}>{`timestamp
nonce
POST
/api/client/v1/orders
sha256(body) = <实际请求 body 字节的 SHA256 十六进制>`}</pre>
<pre style={preStyle}>{`# body = {"client_order_no":"shop-10001","sku":"suit_pink_sheep"}
app_key=ak_xxx&body_sha256=<实际请求 body 字节的 SHA256 十六进制>&method=POST&nonce=a1b2c3d4e5f67890&path=/api/client/v1/orders&timestamp=1721450000`}</pre>
</Card>
<Alert
@@ -161,7 +160,8 @@ sha256(body) = <实际请求 body 字节的 SHA256 十六进制>`}</pre>
description={
<ul style={{ margin: 0, paddingLeft: 20 }}>
<li>POST 签名用的 <Text code>body</Text> 必须与实际发送的 body <b>字节级一致</b>,不要签名后再改空格或字段顺序。</li>
<li>签名失败常见原因:secret 错、path 多了 query、body 不一致、时间戳过期、nonce 重复。</li>
<li>value <b>不要</b> URL encode,原样参与拼接。</li>
<li>签名失败常见原因:secret 错、path 多了 query、body 与签名不一致、时间戳过期、nonce 重复、参数未按字典序拼接。</li>
<li>下单接口还需携带 <Text code>Idempotency-Key</Text>,且必须与 <Text code>client_order_no</Text> 一致。</li>
</ul>
}