总体规范

1 消息头规范

  • 请求方式:POST

  • Content-Type: application/json

  • 签名方式:

    • header中定义需要参与签名或者公共的与具体业务无关的属性
    • 将header中需要参与签名的参数按照字母ascii排列组成字符串如:"{"appid":"8c58593ad151","md5":"cb88af352e8871802ec4ce60162df99d","timestamp":"231545134555","token":"eyJhbGciJ9.eyJzdWIiOiJ24i.LVJnaW9uIiwiZXp8","version":"3.1.2"}",并对字符串按照RSA安全哈希算法签名方法进行签名
    • appid: 请在开发者控制台获取
    • RSA密钥:请在开发者控制台获取
    • md5:将body中的json字符串进行MD5计算,32位小写字符串
    • 空字段不参与签名
  • header参数说明

参数名称 参数类型 是否必须 是否参与签名 长度 参数含义 说明
appid String Y Y 32 分配的appid 从开发者控制台获取
bundleId String N Y 32 app的唯一标识
md5 String Y Y 32 消息参数的MD5值 直接对body的json字符串进行计算,json不包含空格和换行,32位小写
msgSeq String N Y 32 消息序列号 000000000001小于32位 没有消息号时不参与签名
timestamp String Y Y 16 时间戳 单位毫秒
token String N Y 32 鉴权令牌 鉴权令牌 不需要鉴权时不参与签名
version String Y Y 16 客户端版本号 如:1.0.0
signature String Y N 256 签名参数的签名值 签名按照上面的顺序组成字符串签名

示例:

appid: fddd156152DCMM
timestamp: 1540255799000
msgSeq: 0000000016
token: 8909876088df4faf843e0460b96513b1
md5: 123456789019a6bbc590eea7df62cb32
Version:2.3.2
signature: aVhwAFO80zOUDjdiuandi/UPqy9d3ANti3pltIhijy2GnJKOYebVXRujSqKlDCTvh5MAy+98py9OfyOSEaIcEzWkSw+9gyJj4AqVfJIXX/vOxNTmQNvlxS52NATWP5yNYqqAI2s67p1Zx9VXFBXCrUra4D7g6CMuEcdwAn+w=
  • body参数说明
参数名称 参数类型 是否必须 参数含义 说明
userId String Y 用户id 示例,非必有字段

如果无参数,仍然需要{}空的json字符串

示例:

{
    "userId":17
}

2 响应报文

  • 参数说明
参数名称 参数类型 是否加密 参数含义 说明
resultCode String Y 响应码 参考响应码定义
resultMsg String Y 响应描述
total Integer N 记录数 分页查询时使用
page Integer N 当前页 分页查询时使用
pageSize Integer N 页大小 分页查询时使用
data Object/List N 版本号 响应数据,支持普通业务数据以及列表两种方式
  • 不带分页
{
    "resultCode":"000000",
    "resultMsg": "成功",
    "data": {
        "userName":"demo",
        "userNickName": "示例"
    }
}
  • 带分页
{
    "resultCode":"000000",
    "resultMsg": "成功",
    "total": 100,
    "page": 1,
    "pageSize": 2,
    "data": [{
        "userName":"demo1",
        "userNickName": "示例1"
    },{
        "userName":"demo1",
        "userNickName": "示例1"
    }]
}

3 响应码

响应码 描述
000000 成功
000001 服务器内部错误
000002 请求内容格式不合法
000003 请求参数不合法
000004 签名验证失败
000005 非法访问
11501 key不存在
11502 签名无效
11503 token无效
11504 token过期
12054 url编码异常

4 header签名方法

 try{
        /*
        Base64:java.util
        PKCS8EncodedKeySpec:java.security
        KeyFactory:java.security
        Signature:java.security
         */
        //需要签名字符串
        String jsonString= "{\"appid\":\"58c8793ad66511e89e060050569d3255\",\"md5\":\"cb88af352e8871802ec4ce60162df99d\",\"timestamp\":\"231545134555\",\"token\":\"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjZXNoaS0wMDMiLCJyZWdpb24iOiJjZXNoaXlzLVJnaW9uIiwiZXhwIjoxNTQyNzYwNzI1LCJpYXQiOjE1NDIxNTU5MjUsImp0aSI6IjE1NDIxNTU5MjU0MzUifQ.ovydm2u5Bc0UP08RttNWrSttyde86gcUK9GxNPDDQp8\",\"version\":\"3.1.2\"}";
        //RSA密钥
        String privateKey = "MIICdwIBADANBgkqhkiG9w0BAQEFAASCAmEwggJdAgEAAoGBAM1BEzOAMVv5aTgM7khzKdcuqM7GjCPQtAoiizWLb924KIAJuGPvJhRMZowa83+4tsYmsdPt+zhOFr6OdsIhfaSHcYAo/N/ehHaot1pO54fWYbIRpuwegj54w+qMdZLxMhzRHy5ZA53j47SVwblSebRGTGpbCRf41xArxdUs+xV3AgMBAAECgYBYn3Vz8jDdvoXw3pxwCdGSCKJ4jX/q4u0pxxqGZwtJF3/dMNU9yP+PGiHY8rYaep3oVsLHd+TVvdnSM18RmTZO8hta51iBcs+zWy7PqY0GiGXNvBC3y3OBOKb49FvXawERzsY7adTmWyHNyS2RGBF7ZGbUPJVPSJiAR5vknOfogQJBAPvnUM+JDZhUzjQRkOyx5KWYT88H1LWXDS5zTTsdqhzBAJc2gjEVVCRL5aWtQS/3q/X++Oo2+wbmp0lTKXKgZjcCQQDQl45hdtqczxAUcP/aCdmIDMqCQNL1oaTtIU/WTrX4N8gjAHR/uBPPfvmxkA5zx7B8ywthAslclfpigVMkfyrBAkEAnY16D7Pq2uH/7rUl7cT9+0yebiC5u7H0Pp9DKLxPD5jvY6RmHYj3jZQi2FLauMOxvDRzPxqQOyq8arIm9Fi6VQJAPbsMbPWintN8m8ARR7KwiN3YNJIAnKbYy0CXgwHKQoonlYw17fJJEpguRwkt7b/EEDp6xJvxgY/1CJ/jPiLQQQJBAO5e2zjoZgM7glOWoz/ks9Kcu9uW8WDevs8JYyRDnxQVKDcNUlfzH3tTgLhuWco3zr2XyDMzrbUvrvOF40LaGzc=";
        Base64.Encoder encoder = Base64.getEncoder();
        Base64.Decoder decoder = Base64.getDecoder();
        PKCS8EncodedKeySpec priPKCS8 = new PKCS8EncodedKeySpec(decoder.decode(privateKey.getBytes()));
        PrivateKey priKey = KeyFactory.getInstance("RSA").generatePrivate(priPKCS8);
        Signature signature = Signature.getInstance("SHA1WithRSA");
        signature.initSign(priKey);
        signature.update(jsonString.getBytes("utf-8"));
        String signarureString = encoder.encodeToString(signature.sign());
    }catch (Exception e){}