# 开发实现
::: details 目录
[[toc]]
:::
## 代码文档
* 为保持代码与文档一致,所有代码的类,函数,属性都必需写入相应的注释。注释以javadoc规范为准。
* 代码文档将使用dokka工具自动化生成。
![开发 dev](./img/dev_001.jpg)
## 实体类定义规范
* 代码文档注释。使用/** */加注释,不可以使用 //。类对象的注释必需添加作者。
* Swagger注解
* 类使用ApiModel注解,description为描述内容。
* 属性使用ApiModelProperty注解,value为描述内容。日期型默认的输出格式与我们要求的数据格式不同,通过加example指写其输出内容。
例如:@ApiModelProperty(value = "创建时间", example = "2019-03-01 10:10:10")
![开发 dev](./img/dev_003.jpg)
![开发 dev](./img/dev_002.jpg)
* Json注解(FastJson)
* 首字母大小不同,不需要加注解。数据字典定义的首字母大写,实体类属性名的首字母小写(按java命名规范),由应用程序统一控制输出的json属性首字母大写;
* 属性名与Json输出名称不一致,要加注解@JSONField。如建筑名称
* 不希望生成到json的属性加serialize = false,@JSONField(name = "SpeedSensor",serialize = false )
* 所有属性默认为空。框架在更新时默认不更新为空的字段
* 在数据中心中默认所有实体类都有lastUpdate与createTime属性
* lastUpdate与createTime只从数据库读取。 @Column注解的insertable=false, updateable=false
* 数据库映射注解(框架使用该注解对数据库进行读写操作)
* @Table注释标注该实体类对应的数据库表,如果数据库表有模式,则name=“模式名.表名”。
* 属性对应数据库表的主键,使用@Id标注释。
* 属性要写入数据库或从数据库读取需加@Column注解,name属性为数据库表对象的字段。
* 插入时不插入数据库的字段@Column注解的insertable=false。
* 更新时不更新数据库的字段@Column注解的updateable=false。
* 实体类可以通过文档中数据库表介绍,根据表自动生成,达到 设计即完成的操作。
## 控制类规范
::: details 查看代码
<<< @/docs/dev/lib/coding/src/PropertyController.kt
:::
标准的通用接口,增删改查统计
### 控制类注解说明
![开发 dev](./img/dev_005.jpg)
* 类使用/** */加注释,不可以使用 //。类对象的注释必需添加作者。
* @Api 在接口文档 swagger 中显示每个对象控制类说明, 并写明当前控制类的作用,代码中书写 @Api 上面代码示例,swagger 显示如下:
![开发 dev](./img/dev_004.jpg)
* @RestController 和 @RequestMapping 是spring 提供的控制类注解,不理解的可以参看 是spring boot注解介绍
![开发 dev](./img/dev_006.jpg)
* 接口函数和类注释一样使用/** */加注释,在注解中一定要写明函数入参的作用,返回的结果
* 接口注解 @ApiOperation 为配合 swagger 显示接口的描述作用在,@ApiOperation 注解里面有 notes 后面可以书写项目的接口说明以及注意事项
* 接口注解 @PostMapping 设备接口的请求方式为 post 并映射接口名, 接口使用 @GetMapping 还是 @PostMapping 根据需求 使用 @PostMapping
### 控制类接口
#### 创建接口
![开发 dev](./img/dev_006.jpg)
* SCreateRequest 创建请求体基类,所有对象统一创建请求体结构
![开发 dev](./img/dev_008.jpg)
* SCreateResponse 应答体基类,统一返回数据结构,创建接口创建成功会把创建的对象返回
![开发 dev](./img/dev_009.jpg)
#### 删除接口
![开发 dev](./img/dev_010.jpg)
* idList: ArrayList\ 请求体对象列表,只需要填写对象 id 即可或填写对象主键
* SBaseResponse 标准的应答基类,在不需要附带参数的时候使用
![开发 dev](./img/dev_011.jpg)
#### 修改接口
![开发 dev](./img/dev_012.jpg)
* SUpdateRequest 修改接口请求基类,统一修改对象的请求体 ,修改对象属性可以指定属性来修改,在 projection 指定修改的属性,置空
![开发 dev](./img/dev_013.jpg)
修改接口支持级联修改,例如修改设备信息,同时修改设备所在的业务空间信息,修改业务空间对应的竖井信息,修改设备对那个的部件的部件信息,支持 n 级修改
#### 查询
![开发 dev](./img/dev_014.jpg)
* SQueryRequest 请求体基类,所有的标准接口都是用相同的基类,分页、去重 、分组、排序、级联查询 、操作符关系符查询,指定返回属性查询,设置请求返回最大数
::: details 查看代码
<<< @/docs/dev/lib/coding/src/SQueryRequest.kt
:::
* SQueryResponse 查询应答基类 返回数据包括 请求页码 请求条数,符合条件的总数量,数据列表 继承自 SBaseResponse 返回成功标志
![开发 dev](./img/dev_015.jpg)
### 统计查询
![开发 dev](./img/dev_016.jpg)
* SCountRequest 统计请求基类,在 filters 中写查询条件
![开发 dev](./img/dev_017.jpg)
* SCountResponse 统计应答基类,只返回统计的数量以及应答装填
![开发 dev](./img/dev_018.jpg)
::: warning 注意
控制类中只写基本的接口函数定义,不允许有逻辑代码,控制类只做接口定义以及说明
:::
## service 规范
![开发 dev](./img/dev_007.jpg)
* 类SObjectService封装了标准的增删改查统计操作,标准操作可以直接使用该类,可以做为接口的标准接口的通用服务类,对于只有标准操作的对象,只需要写好实体类操作类及相关注释即可
* 这里入参使用Property::class.java是因为泛型在编译时使用,运行时泛型信息将被擦除
### 扩展标准接口 service 中代码逻辑
* SObjectService 提供的标准增删改查统计,都可以在执行前或执行后做相应大逻辑操作,定义一个 BuildingService 继承自 SObjectService 然后在 BuildingService 重写对应的函数例如:
![开发 dev](./img/dev_019.jpg)
* 标准接口都会提供对应的 Before 和 Success 的函数可以重写,作相应的逻辑处理
![开发 dev](./img/dev_020.jpg)
* 自定义方法,然后调用 SObjectService 提供的 select insert replace update delete
```metadata json
fun equipInfo(building: Building){
// 插入数据
insert(building)
// 替换,有则替换,无则创建
replace(building)
// 更新
update(building)
// 删除
delete(building)
// 查询
select(SFilter.eq("id","123456")).entity()
} // Fun
```
#### 扩展接口使用
* insert 插入,直接传入插入的数据会返回 Boolean 布尔值 false 或 true,传入的对象一定是 BuildingService 注解一致的
```metadata json
// 插入数据
val insert = insert(building)
```
* replace 替换和插入一样返回布尔值,是否成功传入对象也相同
* update 同样会返回布尔值,传入的对象一样,也可以输入条件更新,或只更新某一个或某几个属性
```metadata json
// 更新
update(building)
// 根据条件更新
update(building,null, SFilter.eq("projectId","Pj1101060001"))
// 指定更新属性
update(building, arrayListOf("name"), SFilter.eq("projectId","Pj1101060001"))
```
* delete 删除 可以指定条件传出,也可以直接删除某一个对象
```metadata json
// 删除
delete(building)
//指定条件删除
delete(SFilter.eq("equipId","Eq110106000145984513212132"))
// 多条件删除
delete(SFilter.eq("name","大厦"),SFilter.eq("type",1))
```
* select 查询可以多条件组合,利用下面要介绍的表达式、逻辑表达式、函数。
```metadata json
// 查询 单条件,可以在 BuildingService类外调用 如下
BuildingService.select(SFilter.eq("id","123456")).exec()
// entity 代表返回单条数据 exec 返回一个列表
// 多条件查询
select(SFilter.eq("name","123456"),SFilter.eq("projectId","Pj1101060001")).exec()
```
### 关系表达式
| 关系 | 后台语法 |
|:--:|:--:|:--:|
| 等于 | SFilter.eq(“属性名”, 值) |
| 不等于 | SFilter.ne(“属性名”, 值) |
| 大于 | SFilter.gt(“属性名”, 值) |
| 大于等于 | SFilter.gte(“属性名”, 值) |
| 小于 | SFilter.lt(“属性名”, 值) |
| 小于等于 | SFilter.lte(“属性名”, 值) |
| 包含 | SFilter.contain(“属性名”, 值) |
| 前缀 | SFilter.startwith(“属性名”, 值) |
| 后缀 | SFilter.endwith(“属性名”, 值) |
| 为空 | SFilter.isnull(“属性名”) |
| 在列表内 | SFilter.inList(“属性名”, arrayList(值1, 值2, ...)) |
* 使用示例:查询 id 为 123456 的 对象
```metadata json
BuildingService.select(SFilter.eq("id","123456")).exec()
```
### 逻辑表达式
| 逻辑 | 后台语法 |
|:--:|:--:|
| 非 | SFilter.not(表达式) |
| 与 | SFilter.and(表达式1, 表达式2) |
| 或 | SFilter.or(表达式1, 表达式2) |
* 示例:查询 type 类型为 1 或 2 的对象
```metadata json
BuildingService.select(SFilter.or(SFilter.eq("type","1"),SFilter.eq("type","2"))).exec()
```
### 函数
| 函数 | 说明 |
|:--:|:--:|
| SLeft(属性名, 长度) | 字符串左截取 |
| SLength(属性名) | 取字符串长度 |
| SLower(属性名) | 字符串转换为小写 |
| SLPad(属性名, 长度, 填充字符) | 左填充字符串 |
| SMid(属性名, 开始位置, 长度) | 从指定位置截取批暄长度字符串 |
| SReverse(属性名) | 字符串逆序 |
| SRight(属性名, 长度) | 字符串右截取 |
| SRPad(属性名, 长度, 填充字符) | 右填充字符串 |
| SSubstring(属性名, 开始位置, 长度) | 从指定位置截取批暄长度字符串 |
| SUpper(属性名) | 字符串转换为大写 |
示例 :查询名称长度等于4个字符
```
BuildingService.select(SFilter.eq(SLength("name"),4)).exec()
```
#### 自定义函数
标准化 实体类、接口类 ,减少开发工作量,以及开发代码量