接口安全
接口概述
环境地址配置
测试环境
生产环境
HTTP协议配置要求
基础协议配置
请求头配置
服务端口和路径信息
/swagger-ui.html 访问连接配置建议
安全规范
签名验证机制
必需的签名参数
1. appId (渠道标识)
appIdappId=100002. timestamp (时间戳)
timestamptimestamp=17095451840003. nonce (随机字符串)
noncenonce=Hs94gj28ka124. sign (签名值)
signsign=2dsoeQW4ZEyA883lbexZUA==参数传递方式
签名验证流程
1.
2.
3.
4.
5.
6.
签名生成算法
JSON参数扁平化规则
1. 嵌套对象处理（使用点号连接）
{
"user": {
"name": "张三",
"profile": {
"age": 25,
"city": "北京"
}
}
}user.name=张三
user.profile.age=25
user.profile.city=北京2. 数组元素处理（使用索引标记）
{
"tags": ["洗车", "保养", "美容"],
"services": [
{"id": "S001", "name": "标准洗车"},
{"id": "S002", "name": "精致洗车"}
]
}tags[0]=洗车
tags[1]=保养
tags[2]=美容
services[0].id=S001
services[0].name=标准洗车
services[1].id=S002
services[1].name=精致洗车3. 复杂嵌套结构处理
{
"order": {
"id": "ORD001",
"items": [
{
"goods": {
"id": "G001",
"name": "标准洗车套餐",
"options": ["内饰清洁", "轮胎护理"]
},
"quantity": 1
},
{
"goods": {
"id": "G002",
"name": "高级美容套餐",
"options": ["打蜡", "镀膜"]
},
"quantity": 2
}
],
"customer": {
"mobile": "13800138000",
"address": {
"province": "北京市",
"city": "北京市",
"district": "朝阳区"
}
}
}
}order.id=ORD001
order.items[0].goods.id=G001
order.items[0].goods.name=标准洗车套餐
order.items[0].goods.options[0]=内饰清洁
order.items[0].goods.options[1]=轮胎护理
order.items[0].quantity=1
order.items[1].goods.id=G002
order.items[1].goods.name=高级美容套餐
order.items[1].goods.options[0]=打蜡
order.items[1].goods.options[1]=镀膜
order.items[1].quantity=2
order.customer.mobile=13800138000
order.customer.address.province=北京市
order.customer.address.city=北京市
order.customer.address.district=朝阳区4. 特殊值处理
5. 扁平化算法实现示例
参数排序和字符串拼 接
1. 参数排序规则（ASCII字典序）
原始参数: timestamp, nonce, appId, mobile, goodsId
排序后: appId, goodsId, mobile, nonce, timestamp数字 < 大写字母 < 小写字母 < 特殊符号
0-9 < A-Z < a-z < [, ., 等2. 键值对拼接格式
key1=value1&key2=value2&key3=value3appId=10000&channelOrderNo=CH202403041234567&cityCode=110100&goodsId=G001&goodsItemId=GI001&mobile=13800138000&nonce=Hs94gj28ka12×tamp=17095451840003. 空值参数过滤规则
4. 完整的字符串拼接算法
MD5计算实现
1. UTF-8字符编码要求
2. MD5哈希计算的具体步骤
3. 签名结果格式要求
2dsoeqw4zeya883lbexzua12 ✓ (32位小写十六进制)2DSOEQW4ZEYA883LBEXZUA12 ✗ (大写字母)
2dsoeqw4zeya883lbexzua ✗ (长度不足32位)
2dsoeQW4ZEyA883lbexZUA== ✗ (包含大写字母和特殊字符)4. 完整的MD5计算实现
5. 签名计算完整流程
项目中的签名计算会输出详细的调试信息：
完整签名生成示例
示例场景
https://washcar-api.fxzb.vip/api/order/create签名参数
appId=10000
nonce=Hs94gj28ka12
timestamp=1709545184000业务参数（请求体）
{
"channelOrderNo": "CH202403041234567",
"mobile": "13800138000",
"goodsId": "G001",
"goodsItemId": "GI001",
"cityCode": "110100"
}渠道密钥
secret=HKKA4sj81FakwFk9签名计算步骤
收集所有参数（URL参数 + 请求体参数），并移除sign参数：
appId=10000
nonce=Hs94gj28ka12
timestamp=1709545184000
channelOrderNo=CH202403041234567
mobile=13800138000
goodsId=G001
goodsItemId=GI001
cityCode=110100按照参数名ASCII字典序排序：
appId=10000
channelOrderNo=CH202403041234567
cityCode=110100
goodsId=G001
goodsItemId=GI001
mobile=13800138000
nonce=Hs94gj28ka12
timestamp=1709545184000按照 key=value&key=value 格式拼接：
stringA = "appId=10000&channelOrderNo=CH202403041234567&cityCode=110100&goodsId=G001&goodsItemId=GI001&mobile=13800138000&nonce=Hs94gj28ka12×tamp=1709545184000"在字符串末尾直接拼接渠道密钥：
stringSign = stringA + secret
stringSign = "appId=10000&channelOrderNo=CH202403041234567&cityCode=110100&goodsId=G001&goodsItemId=GI001&mobile=13800138000&nonce=Hs94gj28ka12×tamp=1709545184000HKKA4sj81FakwFk9"使用UTF-8编码对拼接字符串进行MD5计算：
最终请求
复杂参数示例
{
"order": {
"items": [
{"id": "item1", "quantity": 2},
{"id": "item2", "quantity": 1}
],
"customer": {
"name": "张三",
"contact": {
"mobile": "13800138000",
"email": "zhangsan@example.com"
}
}
}
}appId=10000
nonce=Hs94gj28ka12
order.customer.contact.email=zhangsan@example.com
order.customer.contact.mobile=13800138000
order.customer.name=张三
order.items[0].id=item1
order.items[0].quantity=2
order.items[1].id=item2
order.items[1].quantity=1
timestamp=1709545184000stringA = "appId=10000&nonce=Hs94gj28ka12&order.customer.contact.email=zhangsan@example.com&order.customer.contact.mobile=13800138000&order.customer.name=张三&order.items[0].id=item1&order.items[0].quantity=2&order.items[1].id=item2&order.items[1].quantity=1×tamp=1709545184000"重要注意事项
1.
2.
3.
4.
5.
6.
渠道认证管理
渠道申请和配置指南
渠道申请流程
1. 申请渠道接入
1.
2.
3.
4.
2. 获取appId和secret密钥
10000, 10001, wx123456789HKKA4sj81FakwFk9, Abc123Def456Ghi7893. 渠道配置信息
{
"appId": "10000",
"secret": "HKKA4sj81FakwFk9",
"channelName": "示例渠道",
"status": "active",
"createTime": "2024-03-01T10:00:00Z",
"expireTime": "2025-03-01T10:00:00Z"
}渠道状态管理
1. 渠道状态类型
2. 渠道状态对API访问的影响
{
"code": "200",
"message": "success",
"data": {
// 正常的业务数据
}
}{
"code": "403",
"message": "渠道已暂停，请联系管理员",
"detail": "Channel is suspended"
}{
"code": "403",
"message": "该渠道已被禁用",
"detail": "Channel is disabled"
}{
"code": "401",
"message": "渠道授权已过期，请续期",
"detail": "Channel authorization expired"
}3. 状态变更通知
{
"appId": "10000",
"oldStatus": "active",
"newStatus": "suspended",
"changeTime": "2024-03-15T14:30:00Z",
"reason": "账户余额不足",
"operator": "system"
}渠道参数传递方式
1. URL查询参数传递（推荐方式）
2. 请求头传递（备选方式）
3. 混合传递方式
在某些特殊情况下，可以采用混合方式传递参数：
4. 参数传递最佳实践
1.
2.
3.
4.
渠道配置验证
1. 配置有效性检查
{
"code": "200",
"message": "验证成功",
"data": {
"appId": "10000",
"status": "active",
"permissions": ["order.create", "order.query", "goods.list"],
"rateLimit": {
"maxRequestsPerMinute": 1000,
"currentUsage": 45
}
}
}2. 配置问题排查
{
"code": "404",
"message": "未查询到渠道，请稍后再试",
"solution": "检查appId是否正确，或联系管理员确认渠道状态"
}{
"code": "403",
"message": "该渠道已被禁用",
"solution": "联系管理员了解禁用原因并申请恢复"
}{
"code": "403",
"message": "渠道接口已过期",
"solution": "检查ChannelApi配置或申请接口权限续期"
}1.
2.
3.
4.
5.
密钥使用和权限验证
密钥在签名中的使用方式
1. 密钥获取优先级
1.
2.
2. ChannelApi配置的优先级规则
3. 密钥在签名计算中的使用
参数字符串 + 密钥参数字符串: "appId=10000&mobile=13800138000&nonce=abc123×tamp=1709545184000"
密钥: "HKKA4sj81FakwFk9"
最终字符串: "appId=10000&mobile=13800138000&nonce=abc123×tamp=1709545184000HKKA4sj81FakwFk9"4. 密钥安全使用规范
渠道验证失败的排查方法
1. 常见验证失败场景
1.
2.
3.
4.
1.
2.
3.
4.
1.
2.
3.
4.
2. 签名验证失败排查步骤
3. 调试工具和方法
4. 问题解决方案
权限验证机制
1. 多层权限验证
1.
2.
3.
4.
2. 权限配置管理
3. 权限异常处理
{
"code": "403",
"message": "权限不足",
"detail": "渠道 10000 缺少权限: order.create",
"requiredPermission": "order.create",
"availablePermissions": ["order.query", "goods.list"]
}错误处理指南
标准错误响应格式
统一响应结构
ApiResponse类，标准响应结构如下：{
"code": 200,
"message": "success",
"data": {
// 业务数据（成功时返回）
}
}响应字段说明
| 字段名 | 类 型 | 必需 | 说明 |
|---|---|---|---|
| code | int | 是 | 响应状态码，200表示成功，其他值表示错误 |
| message | string | 是 | 响应消息，成功时为"success"，错误时为具体错误信息 |
| data | object | 否 | 业务数据，仅在成功时返回，错误时可能为null |
错误响应分类
1. 签名验证错误 (SignException)
101触发场景: 请求签名验证失败
异常类:
cn.xsoft.washcar.exception.SignException{
"code": 101,
"message": "签名不匹配",
"data": null
}2. 参数验证错误 (ArgumentsException)
301触发场景: 请求参数格式错误或缺失
异常类:
cn.xsoft.exceptions.ArgumentsException{
"code": 301,
"message": "参数(fieldName)错误：具体错误信息",
"data": null
}{
"code": 301,
"message": "参数(appId)错误：渠道appId不存在",
"data": null
}appId: 渠道标识不存在或格式错误timestamp: 时间戳格式错误或超出有效范围nonce: 随机字符串缺失sign: 签名参数缺失cityCode: 城市编码格式错误goodsId: 商品ID不存在或已下架orderNo: 订单号不存在3. 方法参数验证错误 (MethodArgumentNotValidException)
301触发场景: Spring Validation注解验证失败
异常类:
org.springframework.web.bind.MethodArgumentNotValidException{
"code": 301,
"message": "参数(fieldName)错误:验证失败信息",
"data": null
}{
"code": 301,
"message": "参数(mobile)错误:手机号格式不正确",
"data": null
}4. 非法参数错误 (IllegalArgumentException)
300触发场景: 参数值不符合业务规则
异常类:
java.lang.IllegalArgumentException{
"code": 300,
"message": "参数错误 详细：具体错误描述",
"data": null
}5. 业务逻辑错误 (ServiceException)
503触发场景: 业务逻辑处理失败
异常类:
cn.xsoft.exceptions.ServiceException{
"code": 503,
"message": "接口异常 详细：具体业务错误信息",
"data": null
}6. 系统运行时错误 (RuntimeException)
501触发场景: 系统内部运行时异常
异常类:
java.lang.RuntimeException{
"code": 501,
"message": "内部异常 详细：系统错误描述",
"data": null
}7. Thrift服务错误 (TException)
502 或 具体业务错误码触发场景: 后端Thrift服务调用异常
异常类:
org.apache.thrift.TException{
"code": 502,
"message": "未处理异常 详细：Thrift服务错误信息",
"data": null
}{
"code": 具体业务错误码,
"message": "具体业务错误信息",
"data": null
}错误码规范
错误码分类
| 错误码范围 | 错误类型 | 说明 |
|---|---|---|
| 200 | 成功 | 请求处理成功 |
| 101 | 签名错误 | 签名验证失败 |
| 300-399 | 参数错误 | 请求参数相关错误 |
| 500-599 | 系统错误 | 服务端内部错误 |
具体错误码定义
| 错误码 | 错误类型 | 说明 |
|---|---|---|
| 200 | SUCCESS | 请求成功 |
| 101 | SIGN_ERROR | 签名验证失败 |
| 300 | ILLEGAL_ARGUMENT | 非法参数 |
| 301 | INVALID_PARAMETER | 参数验证失败 |
| 501 | RUNTIME_ERROR | 运行时异常 |
| 502 | THRIFT_ERROR | Thrift服务异常 |
| 503 | SERVICE_ERROR | 业务逻辑异常 |
错误信息格式规范
参数错误信息格式
参数({参数名})错误：{具体错误描述}参数(appId)错误：渠道appId不存在参数(goodsId)错误：商品不存在或已下架参数(cityCode)错误：城市编码有误参数(orderNo)错误：订单不存在业务错误信息格式
接口异常 详细：{具体业务错误描述}接口异常 详细：未查询到对应核销码接口异常 详细：订单不存在或手机号为空接口异常 详细：获取预约链接失败,请稍候重试系统错误信息格式
内部异常 详细：{系统错误描述}内部异常 详细：数据库连接超时内部异常 详细：JSON解析失败HTTP状态码说明
code字段来表示。这种设计的优势：1.
2.
3.
200 OK: 所有正常响应（包括业务错误）500 Internal Server Error: 仅在Thrift服务异常时使用错误响应示例
成功响应示例
{
"code": 200,
"message": "success",
"data": {
"orderId": "ORD202403041234567",
"orderStatus": "CREATED",
"createTime": "2024-03-04T12:34:56Z"
}
}签名验证失败
{
"code": 101,
"message": "签名不匹配",
"data": null
}渠道不存在
{
"code": 301,
"message": "参数(channelId)错误：未查询到渠道，请稍后再试",
"data": null
}渠道被禁用
{
"code": 301,
"message": "参数(channelId)错误：该渠道已被禁用",
"data": null
}渠道接口过期
{
"code": 301,
"message": "参数(channelApiAuth)错误：渠道接口已过期",
"data": null
}商品不存在
{
"code": 301,
"message": "参数(goodsId)错误：商品不存在或已下架",
"data": null
}订单创建失败
{
"code": 503,
"message": "接口异常 详细：商品库存不足，无法创建订单",
"data": null
}系统内部错误
{
"code": 501,
"message": "内部异常 详细：数据库连接超时",
"data": null
}常见错误类型和解决方案
签名验证失败错误处理
错误类型1: 签名不匹配
{
"code": 101,
"message": "签名不匹配",
"data": null
}1.
2.
3.
4.
5.
6.
appId: 渠道标识，数字字符串timestamp: 13位毫秒级时间戳nonce: 随机字符串，8-32位sign: 32位小写十六进制字符串1.
2.
3.
错误类型2: 时间戳超出有效范围
{
"code": 301,
"message": "参数(timestamp)错误：请求时间戳超出有效范围",
"data": null
}渠道验证失败错误处理
错误类型1: 渠道不存在
{
"code": 301,
"message": "参数(channelId)错误：未查询到渠道，请稍后再试",
"data": null
}1.
2.
错误类型2: 渠道被禁用
{
"code": 301,
"message": "参数(channelId)错误：该渠道已被禁用",
"data": null
}1.
2.
3.
错误类型3: 渠道接口过期
{
"code": 301,
"message": "参数(channelApiAuth)错误：渠道接口已过期",
"data": null
}1.
2.
3.
参数格式错误处理
错误类型1: 必需参数缺失
{
"code": 301,
"message": "参数(mobile)错误：手机号不能为空",
"data": null
}mobile: 用户手机号goodsId: 商品IDcityCode: 城市编码channelOrderNo: 渠道订单号错误类型2: 参数格式错误
{
"code": 301,
"message": "参数(mobile)错误：手机号格式不正确",
"data": null
}错误类型3: 业务规则验证失败
{
"code": 301,
"message": "参数(goodsId)错误：商品不存在或已下架",
"data": null
}1.
2.
常见问题排查步骤
问题排查工具
系统性排查流程
错误日志分析
[签名]
签名字符串：appId=10000&channelOrderNo=CH202403041234567&cityCode=110100&goodsId=G001&goodsItemId=GI001&mobile=13800138000&nonce=Hs94gj28ka12×tamp=1709545184000HKKA4sj81FakwFk9
签名结果：a1b2c3d4e5f6789012345678901234ab=== 签名计算调试 ===
1. 原始参数: {...}
2. 排序后的键: [...]
3. 参数字符串: ...
4. 签名字符串: ...
5. 计算签名: ...修改于 2026-01-01 21:01:55