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