后端代码规范

最新推荐文章于 2025-10-24 11:02:22 发布

原创最新推荐文章于 2025-10-24 11:02:22 发布 · 1.1k 阅读

1 ·

CC 4.0 BY-SA版权

文章标签：

#代码规范 #mybatis #java

文章讲述了Java后端API设计的一些关键点，包括避免使用实体类作为参数，除非明确注解；确保必填参数校验；使用枚举类处理响应状态；指定@RequestMapping的HTTP方法；记录日志和异常处理；在Service层使用具体参数而非对象；MyBatisSQL关键字大写；优化批量操作；删除无效引用和方法；以及避免无用定义。

1、报文入参尽量避免使用实体类（如果用实体类接受参数，一定要写好注解，具体用到了实体类的哪一个属性）

/**
	 * 
	 * @Description: 新增玉米观测记录主表信息
	 * @param @param params
	 * @param @return 参数
	 * @return Result 返回类型
	 * @author 魏振申
	 * @throws
	 */
	@ApiOperation(value = "玉米选定测产信息新增", notes = "玉米选定测产信息新增接口")
	@ApiResponses(value = { @ApiResponse(code = 200, message = "查询成功", responseContainer = "com.rhxt.util.Result"),
			@ApiResponse(code = 650, message = "参数缺失")})
	@RequestMapping(value = "/insertMaizeRInfo", method = RequestMethod.POST)
	public Result insertMaizeRInfo(@ApiJsonObject(name = "insertMaizeRInfo", value = {
            @ApiJsonProperty(key = "userId", example = "1", description = "当前登录用户id ", type = "string", required = true),
	})@RequestBody JSONObject params) {
		Result result = new Result();
		Map<String, Object> dataMap = new HashMap<>();
		if (JSONUtils.checkParams(params, "userId", "testCode", "cropKind")) {
			String rowNum = params.containsKey("rowNum")?params.getString("rowNum"):null;
			String rowLength = params.containsKey("rowLength")?params.getString("rowLength"):null;
			String spikeNum = params.containsKey("spikeNum")?params.getString("spikeNum"):null;
			String plantNum = params.containsKey("plantNum")?params.getString("plantNum"):null;
			String doubleSpikeNum = params.containsKey("doubleSpikeNum")?params.getString("doubleSpikeNum"):null;
			String emptyRodNum = params.containsKey("emptyRodNum")?params.getString("emptyRodNum"):null;
			String downNum = params.containsKey("downNum")?params.getString("downNum"):null;
			String theoryYield = params.containsKey("theoryYield")?params.getString("theoryYield"):null;
			String actualYield = params.containsKey("actualYield")?params.getString("actualYield"):null;
			String quadratArea = params.containsKey("quadratArea")?params.getString("quadratArea"):null;
			String maizeRId = params.containsKey("maizeRId")?params.getString("maizeRId"):null;
			String userId = params.getString("userId");
			String testCode = params.getString("testCode");
			String cropKind = params.getString("cropKind");
			int count = iMaizeTestService.insertMaizeRInfo(rowNum, rowLength, spikeNum, plantNum, doubleSpikeNum, emptyRodNum, downNum, theoryYield, actualYield, quadratArea, userId, testCode, cropKind, maizeRId);
			switch (count) {
			case 0: case 2: case 3:
				result.setCode(ResponseEnum.OPERATION_ERROR.getCode());
				result.setMsg(ResponseEnum.OPERATION_ERROR.getMsg());
				break;
			case 1:
				result.setCode(ResponseEnum.OPERATION_SUCCESS.getCode());
				result.setMsg(ResponseEnum.OPERATION_SUCCESS.getMsg());
				dataMap = iMaizeTestService.selectMaizeYieldInfo(testCode);
				break;

			default:
				break;
			}
		} else {
			result.setCode(ResponseEnum.PARAM_LOSE_EXCEPTION.getCode());
			result.setMsg(ResponseEnum.PARAM_LOSE_EXCEPTION.getMsg());
		}
		result.setObj(dataMap);
		return result;
	}

2、入参必填校验务必要做，入参类型为map、JSONObject类型的我们均配置的有统一校验方法

JSONUtils.checkParams(params, "userId", "testCode", "cropKind")

3、响应数据务必使用封装好的枚举类及对应的结果类

（响应枚举类尽量放在controller层处理）
4、修改数据配合前端失焦及延时保存传值，应做到哪个发生变化，修改哪个，而不是每次全行修改

5、swagger注解务必添加，并配备真实入参及描述信息

6、如使用@RequestMapping注解，需指定method类型

7、关键点增加日志记录及异常信息捕捉输出

8、service层方法入参应以具体的参数为主，而非对象传参

（所有的参数在controller层中接受成具体的属性，之后传到service中）

9、mybatis中sql关键字必须大写

10、删除无用引入包、无用变量、无用mapper方法

11、为了避免obj为null的现象，应该这样写

查询

新增，修改，删除这样写（在setObj的时候把查询的列表数据放进去，因为前端还要做列表刷新）

/**
	 * 
	 * @Description: 新增玉米叶绿素含量记录
	 * @param @param params
	 * @param @return 参数
	 * @return Result 返回类型
	 * @author 魏振申
	 * @throws
	 */
	@ApiOperation(value = "新增玉米叶绿素含量记录", notes = "新增玉米叶绿素含量记录")
	@ApiResponses(value = { @ApiResponse(code = 200, message = "查询成功", responseContainer = "com.rhxt.util.Result"),
			@ApiResponse(code = 650, message = "参数缺失")})
	@RequestMapping(value = "/insertChlorophyllInfo", method = RequestMethod.POST)
	public Result insertChlorophyllInfo(@ApiJsonObject(name = "insertChlorophyllInfo", value = {
            @ApiJsonProperty(key = "userId", example = "1", description = "当前登录用户id ", type = "string", required = true),
	})@RequestBody JSONObject params) {
		Result result = new Result();
		List<ChlorophyllRPojo> listData = new ArrayList<>();
		if (JSONUtils.checkParams(params, "userId", "testCode", "cropKind")) {
			String cropPhase = params.containsKey("cropPhase")?params.getString("cropPhase"):null;
			String chlorophyll = params.containsKey("chlorophyll")?params.getString("chlorophyll"):null;
			String chlId = params.containsKey("chlId")?params.getString("chlId"):null;
			String userId = params.getString("userId");
			String testCode = params.getString("testCode");
			String cropKind = params.getString("cropKind");
			int count = iMaizeTestService.insertChlorophyllInfo(cropPhase, chlorophyll, userId, testCode, cropKind, chlId);
			switch (count) {
			case 0:
				result.setCode(ResponseEnum.OPERATION_ERROR.getCode());
				result.setMsg(ResponseEnum.OPERATION_ERROR.getMsg());
				break;
			case 1:
				result.setCode(ResponseEnum.OPERATION_SUCCESS.getCode());
				result.setMsg(ResponseEnum.OPERATION_SUCCESS.getMsg());
				listData = iMaizeTestService.selectChlorophyllInfo(testCode, cropKind);
				break;
			case 2:
				result.setCode(ResponseEnum.OPERATION_ERROR.getCode());
				result.setMsg("数据存储入库异常");
				break;
			case 3:
				result.setCode(ResponseEnum.OPERATION_ERROR.getCode());
				result.setMsg("数据转换异常");
				break;
			}
		} else {
			result.setCode(ResponseEnum.PARAM_LOSE_EXCEPTION.getCode());
			result.setMsg(ResponseEnum.PARAM_LOSE_EXCEPTION.getMsg());
		}
		result.setObj(listData);
		return result;
	}

12、批量的新增需要批量新增

这种需要处理成批量插入（错误写法）

正确示范

service

/**
     * @description: 主阀关联批量添加分阀（新增）
     * @author: 赵书正
     * @date: 2023/3/27 17:28
     * @param: [fCodes, zCode]
     * @return: int
     **/
    @Override
    public int insertValveZF(String fCodes, String zCode) {
        int count = 0;
        //先删除掉所有跟zCode关联的分阀门
        try {
            count = valveZFMapper.deleteByZCode(zCode);
        } catch (Exception e) {
            log.info("删除掉所有跟zCode关联的分阀门出现异常，异常位置：ValveZFServiceImpl.deleteByZCode，异常原因：", e);
        }
        List<ValveZFPojo> list = new ArrayList<>();
        if (G4Utils.isNotEmpty(fCodes)) {
            String[] fCodeArr = fCodes.split(",");
            for (String fCode : fCodeArr) {
                ValveZFPojo valveZFPojo = new ValveZFPojo();
                valveZFPojo.setId(G4Utils.getUUID());
                valveZFPojo.setzCode(zCode);
                valveZFPojo.setfCode(fCode);
                valveZFPojo.setCreateTime(G4Utils.getLocalDateTime("yyyy-MM-dd HH:mm:ss"));
                list.add(valveZFPojo);
            }
            try {
                count = valveZFMapper.insertValveZF(list);
            } catch (Exception e) {
                log.info("主阀关联批量添加分阀出现异常，异常位置：ValveZFServiceImpl.insertValveZF，异常原因：", e);
            }
        } else {
            count = 1;
        }
        return count;
    }

xml

<insert id="insertValveZF" parameterType="com.rhxt.platform.basic.pojo.ValveZFPojo">
    insert into VALVE_Z_F (ID, Z_CODE, F_CODE, 
      CREATE_USE, CREATE_TIME)
    values
    <foreach collection="list" index="index" item="item" separator=",">
      (#{item.id,jdbcType=VARCHAR},
       #{item.zCode,jdbcType=VARCHAR},
       #{item.fCode,jdbcType=VARCHAR},
       #{item.createUse,jdbcType=VARCHAR},
       #{item.createTime,jdbcType=TIMESTAMP})
    </foreach>
  </insert>

13.批量删除也要做成批量的

错误写法（改成批量的）

正确写法

/**
     * @description: 主阀关联批量添加分阀（移除）
     * @author: 赵书正
     * @date: 2023/3/27 17:29
     * @param: [fCodeArr, zCode]
     * @return: int
     **/
    @Override
    public int deleteValveZF(String[] fCodeArr, String zCode) {
        int count = 0;
        try {
            count = valveZFMapper.deleteValveZF(fCodeArr, zCode);
        } catch (Exception e) {
            log.info("主阀关联批量添加分阀出现异常，异常位置：ValveZFServiceImpl.deleteValveZF，异常原因：", e);
        }
        return count;
    }

xml

<delete id="deleteValveZF" parameterType="java.lang.String">
    delete from VALVE_Z_F
    where Z_CODE = #{zCode,jdbcType=VARCHAR} AND F_CODE in #{fCodeArr}
  </delete>

14、无用的定义要去掉（无用的定义，浪费系统资源）