MapGIS IGServer

# 开发规约

# IDEA配置

  • 设置Hard wrap宽度为140，Setting->Editor->Code Style->Hard wrap at 140 colomns
  • 支持用户自定义的回车，不勾选Setting->Editor->Code Style->Reformat again to remove custom line breaks

# VS CODE配置

统一vscode配置，安装ESLint,Prettier如下

"editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
},
"eslint.validate": [
    "javascript",
    "javascriptreact",
    "vue-html",
    "vue",
    "html",
    "typescript",
    "typescriptreact"
],
"vetur.format.defaultFormatter.js": "prettier-eslint",
//html的格式化与eslint规则冲突，这里通过保存时eslint来实现格式化
"vetur.format.defaultFormatter.html": "none",
"[vue]": {
    "editor.defaultFormatter": "rvest.vs-code-prettier-eslint"
},
"[typescript]": {
    "editor.defaultFormatter": "rvest.vs-code-prettier-eslint"
},
"[javascript]": {
    "editor.defaultFormatter": "rvest.vs-code-prettier-eslint"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 代码编写规范

# 后端

  • 【强制】在IDEA中安装Alibaba Java Coding Guidelines插件，并解决Error、Blocker、Critical级别的问题；
  • 【强制】javadoc编写要求，针对接口和对外的public方法必须添加完整注释；接口、实现类，只需要在接口上添加javadoc注释即可，实现类上不需要重复添加；不要在代码中留存非完整的javadoc，比如
   //正例1
   /**
    * WFS的getCapabilities接口
    *
    * @param svrName   服务名
    * @param version   版本
    * @param xLinkHref 链接
    * @return xml
    */
   //正例2
   /**
    * WFS的getCapabilities接口
    */
   //反例1
   /**
    * WFS的getCapabilities接口
    *
    * @param svrName
    * @param version
    * @param xLinkHref
    * @return
    */
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

  • 【强制】日志类均使用lombok的@Slf4j来实现(避免手动创建log时，指向的class错误)

  • 【强制】对外的REST API有变更，必须添加完整的Swagger注解

  • 【推荐】资源列表接口：大数据量结果返回使用分页，page参数第一页为1,分页大小参数为pageSize

  • 【推荐】不要将Entity层直接通过REST返回，应该包装Dto类，使用mapStruct进行转换

  • 【推荐】json工具类：尽量使用Jackson、org.json两个框架，不要使用Gson,fastJson等其他json框架

  • 【推荐】在IDEA中安装sonarLint插件，并解决bug、vulnerability类型的问题；在IDEA中commit代码时（默认会执行Alibaba和sonarLint的代码扫描），建议解决上述问题后才能commit代码；可同步服务器的规则设置：在IDEA中配置SonarLint服务器http://192.168.176.10:9000，token为b205f2a9d00e58d5269a08de8fe331d768612b46

# 前端

# ElementUI【推荐】

  • Dialog 默认宽度600px，不要使用百分号表示宽度，内部不要刻意添加margin

  • 右下角按钮 取消 确定，取消为默认样式在左，确定为primary样式在右，size设置为small，不要做其它修改 若600px观感较差，尽量使用450px，其它情况酌情处理

  • 确认框的三个值分别为 cancelButtonText: '取消', confirmButtonText: '确定', type: 'warning'

    取消在左，确定在右 所有删除等危险操作必须有确认框

  • form表单的所有组件的label属性值不要带冒号，跟随框架即可

# REST服务异常处理

  • 服务运行时异常统一由SpringBoot内置异常捕获来处理，支持html、json两种格式，已重定义CustomErrorAttributes，适配错误返回结果，不需要在服务中单独创建异常的Response，只需要在代码中抛出指定的异常即可 ，返回json结构如下

    {
    "success":true,
    "msg":"",
    "code":1,
    "timestamp":"2022-01-01 01:00:00.001",
    "status":200,
    "error":"None",
    "trace":""
}
    1
    2
    3
    4
    5
    6
    7
    8
    9

    添加query参数trace，可返回详细的异常堆栈信息

  • 服务中运行时异常不要随意捕获，交给全局异常处理；除非，不想让程序中断，这里请手动捕获

  • 异常详情见server-api的包com.zondy.mapgis.igs.common.http定义

    • 资源找不到404 NotFoundException

    • 客户端400异常 BadRequestException

    • 服务端500异常 InternalServerErrorException

    • 通用web异常 WebApplicationException

# REST服务设计规范

参考资料

  • https://github.com/marmelab/awesome-rest
  • https://blog.octo.com/en/design-a-rest-api
  • https://blog.csdn.net/li_tiantian/article/details/81586656
  • https://restfulapi.net/resource-naming/

# 命名规范

参考 https://blog.octo.com/en/design-a-rest-api/#case

  • Path

一般只能带资源名词，不要带动词，资源一般用复数，特殊除外；

推荐使用小写驼峰命名（为了保持与参数、body规则一致）；

  • Query/Body

包括Query/Request Body/Respnose Body Json（为了与前端js命名一致），参数命名统一使用小写驼峰；

# Swagger注释规范

目前使用的是OpenApi3，可参考

# API编写

  • swagger html地址： /swagger-ui/index.html

  • @Tag为服务接口大类，使用name属性标识接口的分类，尽量简短

  • @Operation中summary属性尽量简短精炼，详细的描述信息使用description属性

  • @Parameter为参数描述

  • @ApiResponse为返回值描述

  • @Schema为对象描述

  • 所有的description属性支持插入md格式文本，这里可通过{{readme.md}}占位符导入classpath中md文件，比如@Tag(name = "根目录服务", description = "{{api-docs/root/tag.md}}")

# 代码提交规范

← 运维 →