狮牙

大约 6 分钟

项目开发规范

一、名词解释

一方库: 本工程内部子项目模块依赖的库（jar 包）。
二方库: 公司内部发布到中央仓库，可供公司内部其它应用依赖的库（jar 包）。
三方库: 公司之外的开源库，比如apache、 spring、google等发布的依赖（jar 包）。
一级工程 :公司级别项目不包含业务代码，定义所有第三方库或插件等版本。
二级工程：定义为项目级工程，项目级工程默认继承顶级工程依赖版本。并定义本工程使用版本信息。
三级工程：模块级工程，可独立提供rest，dubbo接口服务，可单独启动。

库引用规范

1、一方库由二级工程管理依赖版本，所有三级工程引入依赖去除版本号。

2、二方库可以由二级工程指定版本号，也可继承自顶级工程版本号，三级工程引入去除版本号。如顶级工程未管理包，具有顶级工程普遍使用的依赖包，可升级到顶级工程管理版本号。

3、三方库如具有通用性，如 spring ,spring boot等，由顶级工程引入管理版本，如发现顶级工程未管理，可上报然后判断是否需要加入顶级工程管理，如小范围使用不具所有工程使用的特性，则可以选择在二级系统进行管理。如 fastdfs 等，经过长时间使用后具有所有项目的通用性，可提升到顶级项目管理。

项目通用组件

1、核心依赖包

包含通用工具类，常量，全局异常，异常枚举等公用，不含业务代码。

<dependency>
    <groupId>com.pcitc.si</groupId>
    <artifactId>common-core</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

2、dubbo 核心包

关于dubbo公用类

<dependency>
    <groupId>com.pcitc.si</groupId>
    <artifactId>common-dubbo-core</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

3、common-orm-starter

持久层 starter 提供了mybatis 翻页查询等拦截器。

 <dependency>
    <groupId>com.pcitc.si</groupId>
    <artifactId>common-orm-starter</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

4、common-redis-starter

Redis -starter提供了加载Redis默认配置类。

 <dependency>
    <groupId>com.pcitc.si</groupId>
    <artifactId>common-redis-starter</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

5、common-web-starter

web-starter 提供web项目通用配置类，如swagger等默认配置类

<dependency>
    <groupId>com.pcitc.si</groupId>
      <artifactId>common-web-starter</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

二、项目创建

1、创建dubbo接口项目和web接口项目，必须使用脚手架创建，清参照快速上手指导创建，项目结构如下

每个模块需要创建三个工程 XXXX-web、XXXX-service、XXXX-api XXXX-web 将dubbo服务转换http暴露给网关 XXXX-service 编写具体的业务服务 XXXX-api 编写dubbo接口类

2、引用一方库，二方库需在父项目中 dependencyManagement标签库定义依赖，子模块中依赖一方库不用写版本号，

如引入第三方库具有通用性，则需要有项目公用组件中定义依赖，或者父工程已经引用，

如下为二方库引用

<dependency>
    <groupId>com.pcitc.si</groupId>
    <artifactId>common-core</artifactId>
</dependency>
<dependency>
    <groupId>com.pcitc.si</groupId>
    <artifactId>common-orm-starter</artifactId>
</dependency>

3、引用一组依赖包,如同组织，功能依赖的jar 则版本号如下定义：

<properties>
	<xxx.version>x.x.x</xxx.version>
</properties>

<dependency>
    <groupId>xxx</groupId>
    <artifactId>xxx</artifactId>
 	<version>${xxx.version} </version>
</dependency>

三、接口规范

业务域编码规则

编号	名称	子系统
1	共享服务	101 主数据 102 权限 103 报销报账 104 共享资金 105 文件系统 109 会计引擎
2	财务金融
3	经营创新
4	数据服务
5	供应链业务
9	公共模块	901 用户与权限 902 工作流 903 会计引擎 904 系统消息 905 用户安全中心

接口返回码规范

四：IDE配置

1、开发dubbo服务如开发主机存在多个网卡（虚拟网卡，物理网卡）有可能会出现注册服务时出现注册地址会出现注册错误现象可在容器启动环境中添加 -Ddubbo.protocol.host=需要注册的IP地址 2、本地如果有防火墙尽量关掉，因为调用者调用服务时需要提供者暴露端口提供服务的。

3、已经定义的接口方法如需要进行修改时，禁止修改原方法参数及参数个数，可以定义为新方法或者重载方法。（如原方法参数为string，需要修改为 map类型）

4、idea 设置快捷生成方法注释

5、mybatis 生成代码插件使用

五：异常规范

1.网关全局异常

如通过网关调用系统未找到服务地址，则会封装对象返回code:404 错误

2.子系统全局异常

web应用需要集成 common-web-starter ，默认会拦截所有未被捕获的异常，并封装为系统异常，code为901001，msg为异常massage信息。响应如下

{

"code": "901001",

"data": null,

"msg": "/ by zero"

}

3.dubbo接口异常

1.定义dubbo接口时如存在自定义异常类需要抛出，需要在接口类中定义抛出。调用时发生该异常则可以在调用端可以捕获该异常。否则只能捕获到RuntimeException异常。如下

public interface SysStatusService {
    SysStatusResponse getSysStatus(SysStatusRequest request) throws BizException;
}

2.如定义自定义异常需要继承自 BizException

4.自定义错误代码枚举类

自定义错误代码枚举类需要实现 IResultCode接口，如下

@AllArgsConstructor
@NoArgsConstructor
public enum ResultCode implements IResultCode, Serializable {
    SUCCESS("000000","一切ok"),
    USER_ERROR("900001","用户端错误"),
    USER_LOGIN_ERROR("A0200","用户登录异常")
    @Override
    public String getCode() {
        return code;
    }
    @Override
    public String getMsg() {
        return msg;
    }
    private String code;
    private String msg;
    }

六：关于代码删除变更规范说明

1：代码如需修改参数类型，数量，返回值等影响调用者产生语法错误或运行时错误需要使用Java重载特性编写新方法以兼容旧方法实现方式。如旧方法不推荐使用，可用注解 @Deprecated 标注，并注释方法不推荐使用原因，及替代方法名等信息。

2：代码如存在弃用情况，通过@Deprecated 标注(调用时也会出现删除线,但并不代表不能用)，并注释方法弃用原因及替代方案等信息。

3：所有的 POJO 类属性必须使用包装数据类型,RPC 方法的返回值和参数必须使用包装数据类型。任何NPE 问题，或者入库检查，都由使用者来保证。正例:数据库的查询结果可能是 null，因为自动拆箱，用基本数据类型接收有 NPE 风险。反例:比如显示成交总额涨跌情况，即正负 x%，x 为基本数据类型，调用的 RPC 服务，调用不成功时，返回的是默认值，页面显示为 0%，这是不合理的，应该显示成中划线。所以包装数据类型的 null 值，能够表示额外的信息，如:远程调用失败，异常退出。

4：定义 DO/DTO/VO 等 POJO 类时，不要设定任何属性默认值。反例:POJO类的gmtCreate默认值为new Date();但是这个属性在数据取时并没有置入具体值，在更新其它字段时又附带更新了此字段，导致创建时间被修改成当前时间。 POJO 类必须写 toString 方法。使用 IDE 的中工具:source> generate toString 时，如果继承了另一个 POJO 类，注意在前面加一下 super.toString。说明:在方法执行抛出异常时，可以直接调用 POJO 的 toString()方法打印其属性值，便于排查问题。

# 项目开发规范

# 一、名词解释

# 二、项目创建

# 三、接口规范

# 四：IDE配置

# 五：异常规范

# 1.网关全局异常

# 2.子系统全局异常

# 3.dubbo接口异常

# 4.自定义错误代码枚举类

# 六：关于代码删除变更规范说明