接口开发规范(1)

文档书写

开发应该先编写详细接口文档,确定输入输出的命名,类型后再进行开发,避免后续需要修改,同时也可以让需要用到该接口的前端尽早开始开发流程。文档示例如下:

接口名称:XXX
调用关系:XXX前端->XXX后端

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
Schema: HTTP
Path: /api/v1/job/getXXX
Header:
content-type: application/json;charset=UTF-8
Method: POST
body:
{
"uid": "STRING", // 用户id
"jobsNum": "STRING" //
}

// Response
Status Code: 200
body:
{
"traceId": "STRING",
"msgCode": "STRING",
"msg": "STRING",
"data": [
{
"jobId": "String", //
"jobName": "String", //
"createTime": "String", //
"createUserId": "String", //
"status": Integer, //
"clusterId": "String", //
"runtime": "String" //
}
]
}

接口输入输出

接口接受的Dto

每个接口接受的RspDto需要额外编写,尽量不要复用他人的Dto类,因为如果他人的业务逻辑改了,比如改变一个属性的名称,会影响到自己的业务,所以需要尽可能解耦。

接口返回

接口返回应该用ReturnBase封装起来,可以自动处理接口调用报错等信息

1
2
3
4
5
6
7
8
@PostMapping("/getXXXX")
@ApiOperation("description")
// @OnlyIntranetAccess (内网调用)
public ResponseEntity<ReturnBase> getXXXX(){
return Optional.of(Service.getXXXX())
.map(ret->new ResponseEntity<>(ret,HttpStatus.OK))
.orElseThrow(()->new MMException("error.job.getXXXX",ReturnEnum.C_GENERAL_BUSINESS_ERROR.getMsgCode()));
}

接口返回处理

  • 处理用ReturnBase封装的接口返回信息时,需要序列化和反序列化,举例如下:
1
2
String XXXXStr=JsonUtil.jsonObj2Str(XXXXReturn.getData());
List<XXXXRspDto> XXXX=JsonUtil.jsonArrayStr2jsonArray(XXXXStr,XXXXRspDto.class);
  • enum枚举类在序列化和反序列化后需要在枚举类上添加@SerializedName注解,否则会变成0。value需要一一对应,如下:
1
2
@SerializedName("0")
DELETE(0,"删除","Delete"),
  • 对于返回的信息需要对各项空值进行判断,防止取数据的时候产生报错
1
2
3
4
5
6
7
8
9

if(Objects.isNull(getXXXReturn)||
Objects.isNull(getXXXReturn.getData())||
!ReturnEnum.SUCCESS.getMsgCode().equals(getXXXReturn.getMsgCode())){
log.error("get user info by username({}) from aide-user failed, msg={}"
,XXX,
Objects.isNull(getUidByNameReturn)?"null":getXXXReturn.getMsg());
return null;
}

log等级设置

用log日志打印的时候,需要判断打印内容长度是否很多,如果内容很多需要使用log.debug而不是log.info。同时在log记录前需要对当前的log
level做一个判断,避免不必要的操作


尽可能规避硬编码

文本部分尽量避免硬编码,可以采用yml文件配置custom的方式,例如在文本部分尽量避免硬编码,可以采用yml文件配置的方式,例如:

1
2
3
4
5
6
7
8
custom:
bot:
feishu:
allSlurmJobOfUserPara:
defaultJobsNum: "15"
nRow: "-n"
noJobsReturn: "没有查询到任务"
jobsReturn: "查询到{jobsNum}条任务记录:\n"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
package org.openmmlab.platform.aidebot.property;

import cn.hutool.log.LogFactory;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.context.annotation.Configuration;

import java.util.List;

@Configuration
@ConfigurationProperties(prefix = "custom")
@Data
@RefreshScope
public class CustomProperty {
private Bot bot;

@Data
public static class Bot {
private Feishu feishu;

@Data
public static class Feishu {
private AllSlurmJobOfUserPara allSlurmJobOfUserPara;

@Data
public static class AllSlurmJobOfUserPara {
private String defaultJobsNum;
private String nRow;
private String noJobsReturn;
private String jobsReturn;
}
}
}
}


kafka

本地运行项目不需要kafka,在项目路径中找到kafka目录,将里面的配置注释掉,否则会报如下错误

1
WARN [AdminClient clientId=adminclient-1] Connection to node -1 (localhost/127.0.0.1:9092) could not

接口开发规范(1)
https://shouldbeldy.github.io/2023/01/30/接口开发规范-1/
作者
Daoyu Lei
发布于
2023年1月30日
许可协议