开发工程规范

一、工程名称命名

工程命名由三部分组成：前缀-项目名称-后缀。
工程根据功能分为：手机工程和一般性工程，手机工程主要给手机端及 app 提供页面和接口，除手机之外的工程统一称为一般性工程，由前缀决定。
工程根据访问渠道分为：外部工程和内部工程，外部工程的主要用户为外部注册用户，对公网开放，内部工程的访问用户为公司内部人员，只能在公司内网访问，由后缀决定。

1.1 前缀：前缀决定工程的功能

前缀	说明
`mobile`	基于手机浏览器的 `web` 项目，主要提供 `h5` 页面
`android`	关于安卓手机的 `native app` 项目
`ios`	关于 ios 手机的 `native app` 项目
`ins`	公司的一般项目，非手机类项目都使用该前缀

1.2 项目名称

项目名称需要和项目内容非常贴切，让人一看就知道项目是干什么的，命名需要leader、部门总监，一起评审，通过后才能使用。

1.3 后缀：后缀决定工程的功能和使用用户

后缀	说明
`front`	前端项目
`web`	外部工程，提供 `json` 请求，不能提供 `RPC` 接口，此类工程偏向于提供 `web` 页面业务为主
`proxy`	外部工程，提供对外调用接口，不能提供 `RPC` 接口，此类工程偏向于提供外部接口为主
`platform`	内部工程，主要提供 `RPC` 接口服务，另：可以只为技术人员提供一些监控管理的页面，此类工程偏向于 `RPC` 接口为主且只能内网访问
`internal`	内部工程，即可以提供 `RPC` 接口服务也可以提供 `json` 请求，但以 `json` 请求为主。此类工程偏向于提供后台页面为主且只能内网访问，如果此类工程的业务名跟 `platform` 工程的业务名同名，则在业务名后跟 `admin`，以免他们的 `client` 重名冲突。比如：`ins-xy-platform` 和 `ins-xy-internal` 后者应该改为 `ins-xyadmin-internal`.
`task`	以 `main` 函数存在的，通常是以 `jar` 包的形式，不需要容器，独立运行
`app`	手机上安装的软件
`client`	提供 sdk 的客户端
`util`	工具包（`ins-utility` 应该改名为 `ins-common-util`）

1.3.1 示例

车路协同单体提供 pc 端访问的项目应该叫：ins-cvis-web，为车路协同提供手机端页面访问的项目应该叫：mobile-cvis-web。
车路协同给其他端提供业务接口调用的项目应该叫：ins-cvis-platform，为公司内部业务人员提供页面访问的项目应该叫：ins-cvis-internal。
给 app 提供外部接口支持的项目应该叫：ins-xxx-proxy。
像文件系统(lpfs)即需要提供管理页面，又需要提供 RPC 接口调用，还需要给外网提供接口和页面的项目需要根据访问渠道分成外部工程和内部工程两个工程，外部工程应该命名为：ins-lpfs-proxy，因为主要以提供外部接口为主所以后缀应该为 proxy。
内部工程应该命名为：ins-lpfs-platform，因为主要以 RPC 接口为主，且提供的页面只为内部技术人员使用，所以后缀应该为 platform，如果提供的页面是给业务人员使用则应该为：ins-lpfs-internal。

1.4 工程结构包名

com.hiacent.项目名称.web/platform【.模块名】。

如果只有一个业务模块，则业务模块级可以省略。

例如 :

ins-biz-web:工程结构包名:com.hiacent.biz.web【.模块名】
ins-user-platform:工程结构包名：com.hiacent.user.platform【.模块名】

工程字符集: 工程符集全部设定为 UTF-8 格式

二、继承结构及工程规范

模块名称	模块说明	示例	备注
`entity` 层	实体类命名与表名相同，首字母大写，如果表名存在那么将这去掉后首字母大写。	表名:like_log 实体名 LikeLog	实体类属性必须与数据库字段名保持一致。
`dao` 层	继承 `com.baomidou.mybatisplus.core.mapper.BaseMapper<T>` 要求实体泛型 dao 层下接口命名：实体名+Mapper 。	LikeLogMapper
`service` 层	要求：接口继承 `com.baomidou.mybatisplus.extension.service.IService<T>`要求实体泛型
`service.impl` 层类	继承 `com.baomidou.mybatisplus.extension.service.impl.ServiceImpl`，`service` 层下接口命名：`业务名称+Service` 。`service.impl` 层命名：`业务名称+ServiceImpl` 。	`LikeLogService；LikeLogServiceImpl`	`service` 层可以调用 `service` 层和 dao 层和其他项目。 `service` 层下可再包一层 `bean` 层，用以存放数据结构的类，必须以 `Bean` 结尾。平台 `service` 层内部调用的方法可以返回 `entity`，但是被 `manage` 层调用的 `service` 方法只能返回 `dto` 或基本数据类型，不能返回 `entity` 到 `manage`。
`manage` 层	调用其它服务的接口，通常使用 `Feign` 来实现	`ILikeLogMange`	`manage` 层下接口命名：`I+业务名称+Manage`。
`controller` 层	继承:`org.jeecg.common.system.base.controller.JeecgController<T, S extends IService<T>>controller` 层命名：以 `Controller` 结尾。	`LikeLogController`	`web/proxy/internal` 可用；controller 层不能出现 dto
`form` 层	`web/proxy/internal` 可用；`form` 下类命名：以 `Form` 结尾。	`LikeBaseInfoForm`	`form` 可以引用其他 `form` 中不可以包含 `dto`
`dto` 层	`internal/platform` 可用；`dto` 层命名：以 `Dto` 结尾，前缀不一定是 `entity`。	`LikeLogDto`	`dto` 不能引用别人的 `dto`
`schedule` 类	`schedule` 层命名: 以业务名称开头，以 `Schedule` 结尾，前缀不一定是 `entity`。	`SendEmailSchedule`
`Idp` 类	`idp` 层命名：以 `IdpHandler` 结尾。	`ResumeIdpHandler`
`util` 层	`util` 层命名：以 `Util` 或 `Utils` 结尾。	`MoneyUtil`
`consts` 层	静态变量类 `consts` 层命名：以 `Const` 结尾。	`LikeLogConst`
`helper` 层	`helper` 层命名：`client 名+Helper 结尾`。	`UserPlatformClientHelper`	`Helper` 层主要放置调用其它端 `client` 的工具类； `Helper` 只可以出现调平台的代码和处理平台返回错误的代码； `Helper` 不允许调其他 `helper`；
`filter`	`filter` 命名：以 `Filter` 结尾。	`AuthFilter`	只能出现在 `common` 包下面的 `filter` 包中
`resolver`	包名只能叫 `resolver` 且同一工程下只能有一个 `resolve` 包，只能出现在 `common` 包下的 `resolver` 包中，此包下只能有一个类文件且名称为：`MvcExceptionResolver`。

三、数据结构体标准

dto，form，entity，bean 四者间的转换只能通过手动 get，set 方式赋值。

类的静态变量、静态区域块、构造函数中，不允许出现数据库的调用和 RPC 的调用。

3.1 命名标准

同一工程下的受 spring 管理的类的类名不能相同，即使包名不同也不允许类名相同。

3.2 通用标准

Ajax 方法里不能声明 callback 参数，因为此参数在使用跨域时做为系统占用参数。

所有可以通过网页端访问的 URL 命名统一全小写，可以在单词之间用“-”（减号）分隔，controller 采用骆峰格式命名两者除了大小写之外其他尽量保持相同。

例：@RequestMapping("/getassesseeandbranch")

所有 RPC 接口统一用驼峰形式。
返回值是 json 格式 URL 名必须是以.json 结尾.

四、Web URL 标准

Controller 中 URL 的 requestMapping 不能以＂/＂结尾。

例：@RequestMapping("/getassesseeandbranch")

在前端页面中书写的 URL 必须以“/”结尾。

例：<a href="/getassesseeandbranch/">

所有非登录能访问的目录型 url（不是以.*结尾的 url），如果访问时没有“/”结尾，则需要自动加上“/”并作 301 跳转。

例如：http://www.hiacent.com/login?name=xxx 应该 301 跳转到 http://www.hiacent.com/login/?name=xxx。此条只针对 get 请求。

所有非登录能访问的列表页面，所有翻页都需要修改成 http://www.hiacent.com/list/pnX/ (X 为页码）的形式。
ajax 翻页的不用遵循这个规范。

4.1 `Ajax URL` 标准

Ajax 方法必须以.json 结尾．例：@RequestMapping("/getuser.json")

header 头信息里包括 X-Requested-With=XMLHttpRequest 或者带有 callback 参数

4.2 `APP URL` 标准

APP 方法必须以.json 结尾。

例：@RequestMapping("/getuser.json")

请求都是压缩格式，header 头信息里包括 accept-encoding=gzip，不能包含 X-Requested-With=XMLHttpRequest 头信息或 callback 参数。

4.3 Ajax 使用

ajax 请求以.json 结尾，header 头信息里包括 X-Requested-With=XMLHttpRequest 或者带有 callback 参数请求并且是.json 后缀的访问也属于 ajax 请求。

ajax 和 web 根据功能放在同一 controller 里。

请求参数放在方法行参里，不在使用 reqeust 获取请求参数，扁平化参数或封装 form 对象，controller 方法参数扁平话后，大家写对象时一定要定义成 Form，不要用弱对象 map 这些类型。

controller 方法参数不再有 HttpServletRequest、HttpServletResponse，统一在继承的父类 AbstractController 提供方法操作，如 cookie、文件下载等。
返回结果使用方法直接返回 ajax 方法并且，返回值是 json 格式的方法的返回值不需要自己转换 json。

shell

请求形式：http://domain.hiacent.com/uri?key1=value1&key2=value2&...
返回协议体：{"flag":1,"data":{},"code":"","msg":""}
例：
@RequestMapping("/aap.json")
    public List<Integer> aaph(Model model) throws BizException {
        List<Integer> list = new ArrayList<Integer>();
        list.add(1);
        list.add(2);
        return list;
    }

4.4 Ajax 返回数据规范

// 正常返回
{
  "flag": 1,    // 数据状态标识
  "data": {     // 正常返回的相关数据，可以是 Object / Array
    ...
  }
}
// 异常返回
{
  "flag": 0,    // 数据状态标识
  "code": "***",    // 异常标识code
  "msg": "some error message."    // 异常提示信息
}

在正常情况下，后台只返回 flag 和 data 两个字段，异常情况下，返回 flag / code 和 msg 三个字段。对于复杂业务场景，返回正常数据可能包含多种情况，以下面的方式来约束：

{
  "flag": 1,
  "data": {
    "biz_code": "***",
    "msg": "some notice message.",
    "***": "some value"
  }
}

和前端约定：成功失败的返回值（成功 flag=1，失败 flag=0）。

五、手机 `app` 请求

请求以.json 结尾，请求都是压缩格式，header 头信息里包括 accept-encoding=gzip

请求参数放在方法行参里，不在使用 reqeust 获取请求参数，扁平化参数或封装 form 对象，请求参数放在方法行参里，不在使用 reqeust 获取请求参数，扁平化参数或封装 form 对象，controller 方法参数扁平话后，大家写对象时一定要定义成 Form，不要用弱对象 map 这些类型

返回结果使用方法直接返回

请求参数形式：http://domain.lietou.com/uri?mustKey1=v1&mustKey2=v2&data={}

兼容版本返回的协议体：

json

{
  "message": "OK",
  "status": 0,
  "data": {},
  "flag": 1
}

最终版本和 ajax 返回一样。

六、`Cache` 使用

关于缓存的使用规范

所有业务缓存、二级缓存缓存都用 redis，不能用 memcache。
redis 只用作不持久化的缓存

开发工程规范 ​

一、工程名称命名 ​

1.1 前缀：前缀决定工程的功能 ​

1.2 项目名称 ​

1.3 后缀：后缀决定工程的功能和使用用户 ​

1.3.1 示例 ​

1.4 工程结构包名 ​

二、继承结构及工程规范 ​

三、数据结构体标准 ​

3.1 命名标准 ​

3.2 通用标准 ​

四、Web URL 标准 ​

4.1 Ajax URL 标准 ​

4.2 APP URL 标准 ​

4.3 Ajax 使用 ​

4.4 Ajax 返回数据规范 ​

五、手机 app 请求 ​

六、Cache 使用 ​