项目使用原创

# 项目使用

# 加载依赖包

请参考snam-boot 中的snam-business模块 pom.xml结构，必须的构建spring boot微服务包如下（具体请查看快速开始中的项目依赖）

    <dependency>
        <groupId>com.baomibing</groupId>
        <artifactId>snapper-web-starter</artifactId>
        <version>${latestVersion}</version>
    </dependency>

    <dependency>
        <groupId>com.baomibing</groupId>
        <artifactId>snapper-orm-starter</artifactId>
        <version>${latestVersion}</version>
    </dependency>

    <dependency>
        <groupId>com.baomibing</groupId>
        <artifactId>snapper-feign-starter</artifactId>
        <version>${latestVersion}</version>
    </dependency>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

引入权限feign依赖包，通过该包可以进行权限的feign实时调用

    <dependency>
        <groupId>com.baomibing</groupId>
        <artifactId>snam-authority-api</artifactId>
        <version>${latestVersion}</version>
    </dependency>

1
2
3
4
5

提示

上面包为必选包，以下包为可选包，根据功能需求自行选择！

如果需要email相关功能，请添加

    <dependency>
        <groupId>com.baomibing</groupId>
        <artifactId>snapper-email</artifactId>
        <version>${latestVersion}</version>
    </dependency>

1
2
3
4
5

需要http请求相关功能，请添加

    <dependency>
        <groupId>com.baomibing</groupId>
        <artifactId>snapper-http</artifactId>
        <version>${latestVersion}</version>
    </dependency>

1
2
3
4
5

需要文件存储相关功能，请添加

    <dependency>
        <groupId>com.baomibing</groupId>
        <artifactId>snapper-oss-starter</artifactId>
        <version>${latestVersion}</version>
    </dependency>

1
2
3
4
5

# 创建对象模型及分层服务

通常情况下，会根据开发的功能（假设数据库已经设计完成）创建相关的模型及分层机构，snapper项目中会分成如下步骤：

创建实体模型在entitiy包中创建对应的实体模型，并添加相应的注解（参考mybatis-plus注解）
创建DTO模型在dto包中创建对象DTO模型，并添加相应的注解（lombok注解）
创建Mapper并继承BaseMapper(mybatis-plus包中)，请确该包能被@MapperScan（启动类中配置）扫描到
创建controller并继承MBaseController<Dto>，添加相应注解 @RestController，@RequestMapping
创建Service接口
创建ServiceImpl实现类并继承MBaseServiceImpl<Mapper,Entity,Dto>，实现Service接口，添加@Service注解
创建mapper对应的XML，其中的namespace为mapper对应的类路径
添加SPI扩展点，具体为创建类实现BusinessAuthService类，同时在类上添加注解 @AutoService(value = BusinessAuthService.class)，通过feign调用实现对应的方法

# 增删改查

项目中已集成了通用的增删改查功能

在MBaseController中，增、删、改、查（获取对象）对应的@RequestMapper分别为@Post、@Delete、@Put、@Get
Controller中分页查询数据方法参数请定义PageQuery<E>方式，返回类为R<E>方式，其中service对应的方法声明为SearchResult<E> search(E v, int pageNo, int pageSize)方式，其中E为对应DTO
MBaseController中通用的增删改查调用的是MBaseService中的对应的接口，这些接口的在MBaseServiceImpl中已经实现
MService实现类中建议保留原始的增删改查，不要重写（MBaseServiceImpl中会调用默认实现），有业务逻辑的增删改查，建议在Service中重新定义并在对应类中实现，方法命名需要注意事务命名传播机制

# 方法命名事务传播机制

系统中根据不同的命名有默认的事务规则，具体为

save/add/insert/update/delete/do/generate开头的方法为持久化事务
list/get/search/map/sets为只读事务
其他命名的默认为只读事务，如果需要持久化需要在service实现类方法上手动添加@Transactional

# 通用方法及”与我“有关方法

系统内置了一些通用的方法用来获取相关信息及”与我“有关的信息

MBaseController 继承的ActionCOntroller中封装的通用request/response/session等相关通用方法及 currentUser相关的”与我“有关的方法
MbaseServiceImpl继承的ContextServiceImpl中封装了通用的当前request等方法及currentUser相关的”与我“有关的方法

# 异常处理

提示

异常编码的定义，用户可以按照一定的业务规则来定义，比如ORDER微服务以1开头共5位，ORDER中的供应商业务可以在微服的基础上再进行范围划分，这样维护的时候通过编号感知具体业务的错误

系统集成了统一异常的处理方式，具体请查看com.baomibing.web.exception.GlobalExceptionHandler，同时在网关层也进行了统一异常的处理转换，如果该处理方式不满足需求，请参考自定义相关的异常处理
对于业务异常的处理，可以按照如下步骤进行

创建exception包，新建异常枚举类，并实现ExceptionEnumable接口，具体可参考snam-boot/snam-business/WmsExceptionEnum
在异常类中定义异常枚举，异常枚举由编码和业务描述组成，业务描述可以添加{0} {1} ...占位符
通过throw new ServerRuntimeException(ExceptionEnumable,Object..)的方式来抛出业务异常
snapper-tool模块可以通过Assert来断言是否合法，不合法会自动抛出异常，比如Assert.CheckArgument，Assert.beNotNull
MbaseServiceImpl中的持久化（saveIt,updateIt,deletes）都会对参数进行校验，不合法时会抛出异常

# 统一返回

注意

针对feign调用时，会返回原始数据，不会进行数据的统一返回封装，方便feign调用后进行处理!

系统集成了统一返回的处理方式，具体参考com.baomibing.web.common.ReturnHandlerAdvice，要使用统一返回需进行如下步骤

在env对应的配置文件中，赋值snapper.wrap.package变量对应所要进行统一返回的包名，只能配置一个，例如配置com.baomibing，处理时将会判断当前包名是否以com.baomibing开头
返回数据将会统一包装成com.baomibing.web.common.R 类型的JSON数据格式
private方法，返回类型为R、ModleView都不会被处理封装
如果方法不希望被统一返回结果封装，在Controller方法上添加@NotWrap注解

# 打印日志

提示

在logback-spring.xml中，可根据不同的环境配置不同的日志生成信息，通过springProfile对应的环境进行配置！

系统集成了Logback日志组件，具体日志打印信息可在logback-spring.xml进行配置，共有如下几种日志内容

控制台日志，为INFO级别，显示控制台的输出
ROOT日志，为DEBUG级别，展示所有的日志信息
PointLog埋点日志，为DEBUG级别，显示由PointLog类输出的埋点日志
SQLLog日志，为DEBUG级别，展示系统所有的SQL执行语句及返回数据信息

# 业务日志

注意

建议@ULog只记录持久化方法，只读事务的方法不建议记录，具体记录内容请在UI中查看

系统提供了记录业务日志的功能，通过简单添加@ULog即可实现，其中@ULog中的值为该方法的功能作用，具体使用和注意项如下

env环境配置文件中snapper.ulog 设置为true，不设置默认会为true
创建listener包，创建ULogEventListener接口，监听UserLogEvent事件，调用feign保存日志，具体参考com.baomibing.snam.business.listener.ULogEventListener
@ULog用于Controller方法
@ULog是异步的，发布监听后通过feign调用authority模块进行持久化到数据库中（暂时还没用队列）
@ULog会区分hmac授权日志及jwt授权日志，记录不同的表中

← 调试启动权限使用→