接口开发规范(1)

文档书写

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

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

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封装起来，可以自动处理接口调用报错等信息

@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封装的接口返回信息时，需要序列化和反序列化，举例如下：

String XXXXStr=JsonUtil.jsonObj2Str(XXXXReturn.getData());
        List<XXXXRspDto> XXXX=JsonUtil.jsonArrayStr2jsonArray(XXXXStr,XXXXRspDto.class);

• enum枚举类在序列化和反序列化后需要在枚举类上添加@SerializedName注解，否则会变成0。value需要一一对应，如下：

@SerializedName("0")
DELETE(0,"删除","Delete"),

• 对于返回的信息需要对各项空值进行判断，防止取数据的时候产生报错

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文件配置的方式，例如：

custom:
  bot:
    feishu:
      allSlurmJobOfUserPara:
        defaultJobsNum: "15"
        nRow: "-n"
        noJobsReturn: "没有查询到任务"
        jobsReturn: "查询到{jobsNum}条任务记录:\n"

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目录，将里面的配置注释掉，否则会报如下错误

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