# 后端规范
# 一、 系统说明
生产环境下,网关必须需要配置https(微信小程序和IOS强制要求)
只允许**服务网关(gateway微服务)**可外网访问,其他微服务禁止外网访问。
接口文档请看网关接口汇总:http://localhost:8880/doc.html
# 二、命名空间约定
命名空间是根据nacos的命名空间来定义的,所有的值都是指命名空间ID(并不是命名空间名称),所有的服务必须在同一个命名空间才能相互调用。
# 1).应用配置
bootstrap.properties的参数说明
spring.profiles.active=dev
## 这个参数,是应用启动最重要的参数之一。spring.profiles.active和多个配置有关
# 2).配置中心
spring.cloud.nacos.namespace=${spring.profiles.active}
## 这里的namespace指的是nacos的命名空间ID,注意并不是命名空间的名称,为了方便使用,我们设置nacos的命名空间的时候,把名称和ID设置为相同值。特别注意:除了配置nacos的账号密码,命名空间ID配置正确才能读取到配置,应用启动才能成功。否则一般出现读取配置失败,数据库无法连接成功。
# 3).日志配置
roncoo-education\roncoo-education-common\roncoo-education-common-log\src\main\resources\logback-spring.xml
<springProfile name="dev">
## 这里的name和spring.profiles.active的值相对应,按需配置日志即可
## 特别注意:控制台的日志不显示,一般是这里设置不对导致的。
</springProfile>
# 4).Seata配置
seata/conf/registry.conf
registry {
type = "nacos"
nacos {
application = "seata-server"
serverAddr = "127.0.0.1:8848"
group = "SEATA_GROUP"
namespace = "dev"
cluster = "default"
username = "nacos"
password = "nacos"
}
}
config {
type = "nacos"
nacos {
serverAddr = "127.0.0.1:8848"
namespace = "dev"
group = "SEATA_GROUP"
username = "nacos"
password = "nacos"
}
}
## namespace为命名空间ID。
# 三、 规则约定
# 1. 环境参数的约定
所谓的环境参数是指区分本地、开发、测试、生产的环境参数,对应如下:
环境参数 | 说明 |
---|---|
local | 本地环境,调试使用 |
dev | 开发环境,开发使用 |
test | 测试环境,测试使用 |
prod | 生产环境,生产使用 |
环境参数可以按需增减
# 2. 接口工程的约定
roncoo-education-feign下面的所有子工程,都定义为接口工程(提供接口给其他工程调用),包结构如下:
- fallback 断路器实现的类,命名规范:Fallback开头
- interfaces 接口类,命名规范:IFeign开头
- qo 入参实体,命名规范:QO结尾
- vo 出参实体,命名规范:VO结尾
# 3. 服务工程的约定
roncoo-education-service 下面所有的子工程,都定义为服务工程(提供接口给前端调用),包结构如下:
- common
- bo 前端入参实体,命名规则:BO结尾
- dto 前端出参实体,命名规则:DTO结尾
- req 后台入参实体,命名规则:REQ结尾
- resp 后台出参实体,命名规则:RESP结尾
- job 定时任务,分布式调用
- service
- api 前端接口,不需要登录的接口
- auth 前端接口,路径包含关键词:/auth,登录后的接口
- dao 数据层
- feign 工程接口
- pc 后台接口,路径包含关键词:/pc
- api 前端接口,不需要登录的接口
# 4. 服务网关的约定
服务网关的主要功能:转发和鉴权。
转发功能:通过配置中心获取转发规则。
鉴权功能:通过判断请求路径是否包含某个约定的字符串来实现鉴权。
目前鉴权路径为:**/pc 和/auth **
- **/pc **:管理后台接口,进行权限认证,并将loginName放入请求头,后端服务通过获取请求头拿到loginName。
- **/auth **:用户登录后接口,进行登录认证,并将userNo放入请求头,后端服务通过获取请求拿到userNo。
# 5. 前端规范的约定
采用Nuxt.js框架,具体可参考:https://www.nuxtjs.cn/guide
# 四、注意事项
# 1. Feign接口规范
- Get,使用注解@PathVariable接收参数,应该保证幂等。
- Post,使用注解@RequestBody接收参数,不允许出现多个@RequestBody,也不允许使用List接收入参,只能用实体。
# 2. Seata分布式事务
- 目前(2021-01-18)建议使用最新版本1.4.0 ,集群使用DB模式。
- 不允许更新主键操作
# 3. 异常处理
- 在开发过程中,如果要抛远程异常,应该抛系统里面已经定义好的BaseException。