开发规范

# 开发规范

# 1. 接口域名说明

HTTP请求URL约定如下：

请求类型	域名
HTTP POST请求	https://openapi.lechange.cn:443/openapi/[method]

# 2. HTTP请求数据格式说明

开放平台HTTP请求格式约定如下：

参数列表		参数类型	参数说明
system	ver	String	协议版本信息，当前为1.0
	sign	String	签名值，平台用来做签名校验。计算步骤见下文第4节
	appId	String	appId，控制台-我的应用-应用信息中获取
	time	Long	发起接口调用的客户端时间戳（UTC时间戳，单位为秒），该时间与真实时间误差不能超过5分钟
	nonce	String	随机数（32位），nonce在5分钟内不能重复使用，否则返回SN1005错误码
params		Map	HTTP接口方法使用的参数集合，value为组装好的Map对象
id		String	请求唯一标示ID，每次请求调用时传入唯一非空字符串

以获取管理员账号accessToken接口为例，请求数据格式如下：

{
    "system":{
        "ver":"1.0",
        "appId":"lcdxxxxxxxxx",
        "sign":"b7e5bbcc6cc07941725d9ad318883d8e",
        "time":1599013514,
        "nonce":"fbf19fc6-17a1-4f73-a967-75eadbc805a2"
    },
    "id":"98a7a257-c4e4-4db3-a2d3-d97a3836b87c",
    "params":{

    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13

# 3. HTTP响应应答格式说明

开放平台HTTP请求响应返回格式约定如下：

字段列表		字段类型	字段说明
result	code	String	请求返回码，具体详见全局返回码说明
	msg	String	请求返回码描述字符串，具体详见全局返回码说明
	data	Map	请求接口返回的具体内容信息，value为组装好的Map对象
id		String	请求接口时开发者传入的id

以获取管理员账号accessToken接口为例，响应数据格式如下：

{
    "result":{
        "msg":"操作成功。",
        "code":"0",
        "data":{
            "expireTime":259176,
            "accessToken":"At_00006ac6e32d123141238f60147de7ec"
        }
    },
    "id":"98a7a257-c4e4-4db3-a2d3-d97a3836b87c"
}

1
2
3
4
5
6
7
8
9
10
11

# 4. HTTP鉴权sign计算说明

“签名原始串”为time，nonce，appSecret三个参数的键值对拼接，按照time，nonce，appSecret的顺序进行组合，中间以英文逗号分隔。
将“签名原始串”进行MD5处理，并转化为16进制的32位小写字符串，作为签名值sign（注：编码格式为UTF-8）。示例如下：

/**
* 所需代码依赖
*/
import org.apache.commons.codec.digest.DigestUtils;
import java.text.MessageFormat;
import java.time.Instant;

/**
* 计算sign示例
*/
// 1、获取当前时间戳
Long time = Instant.now().getEpochSecond();
// 2、获取随机数
String nonce = UUID.randomUUID().toString();
// 3、appSecret请在控制台-应用信息中获取
String appSecret = "test123456789test123456789";
// 4、生成原始串
String SIGN_TEMPLATE = MessageFormat.format("time:{0},nonce:{1},appSecret:{2}", time.toString(), nonce, appSecret);
// 5、计算sign
String sign = DigestUtils.md5Hex(SIGN_TEMPLATE);

# 标准案例：

原始串为：
String SIGN_TEMPLATE = "time:1706511734,nonce:f5a1ae2d-c09c-4d39-a744-83a5c2c653c2,appSecret:test123456789test123456789";
最终计算sign为：
String sign = "fd37b62889e4757c58b8f3bf05fb9976";
可以参照标准案例，在您本地项目试运行。如果您计算出来sign的值和案例相同，则代表您的计算过程正确。