设计规范及风格

zhoujian

原文链接, https://www.zybuluo.com/windwolf/note/858396

Sailing 之 设计规范及风格

Sailing

---

说明

以下条目都有一个要求等级. 要求等级分两种: 必须, 建议. 意思就是字面意思, 不解释了.

规则
命名
模块

模块ID和模块名称保持一致, 都采用中文名称.

实体

• Entity类名采用中文, Entity的Id=Name=类名
• Element类名采用中文+Part, Element的Id=Name=类名
• Entity和Element的所有字段都采用中文
• Entity和Element的Field必须填写FieldType
  

数据库

• 库表和实体的字段和类型要严格一致. 包括名称和类型.
  

单据, 资源等的实体设计

• 必须 命名
  
  • 模块ID和模块名称保持一致, 都采用中文名称.
  • Entity的Id=Name, 都采用中文名称.
  • Entity类名采用中文, 为模块名_实体名.
  • Element类名采用模块名_实体名Part.
    
• 必须 Entity和Element的Field必须填写FieldType.
• 建议 逻辑上一个实体只能存在一个的东西, 建议附加上接口, 接口内容是一个或若干个Part或字段.
• 必须 凡是需要附加工作流的实体, 都需要实现Stateful接口, 该接口有状态(String), 子状态(String), 工作流实例(Long)三个字段. 实体新建时, 状态统一为[草稿], 后续状态由工作流维护.
• 建议 一对多映射尽量使用Set而不是List
• 必须 一个主表有多个子表(即多个一对多映射)的时候, 统一使用Set, 而不是List. 这是为了方便Fetch操作
• 建议 在Set内子表, 如果业务上可能一个主表数据项下的子表数据, 除主键, 外键外其他字段都相等的情况, 此时必须实现EntityItem接口, 该接口有一个字段: 项号(Integer), 系统维护这个项号. 并在该根项下保持唯一.
• 必须 如果实体要启用版本号控制的变更策略, 那么根实体需要实现VersionedEntity接口, 改接口有一个实体_版本化实体编码Part类型的字段, 该Element有编码(String), 版本号(Integer), 是否当前版本(Boolean)三个字段, 一旦启动流程后, 编码不得修改, 版本号和是否当前版本由版本号控制策略维护.
• 必须 如果实体启用了版本号控制的变更策略, 那么子实体必须使用项号.
• 必须 一个单据如果引用了受版本号控制的实体, 那么要使用实体_版本化实体引用Part这个Element来引用, 而不是id. 如果一个单据的子实体引用了另一个受版本号控制的子实体, 那么要通过实体_版本化实体项目引用Part, 而不是id来引用.
• 必须 凡是有Set的实体, 都要显式的在实体类上加上@EqualsAndHashCode(callSuper = true,exclude = {"XXX", "XXX"}), 用于防止计算HashCode时候的死循环.
• 建议 有text, lob类型大数据字段的, 因为不能使用distinct, 因此在分页等操作中会造成各种问题. 建议独立一个表处理.
• 必须 所有实体都需要加上@EqualsAndHashCode(callSuper = true, exclude = {"一对一", "一对多", "多对一"})和@ToString(callSuper = true, exclude = {"一对一", "一对多", "多对一"}), 其中exclude排除掉一对一, 多对一, 一对多的字段.
  

业务命名约定

• 业务性质: 自营/合营/代理
• 业务场景:
• 收款性质:
• 付款性质:
  

数据库

• 必须 数据库的字段类型和实体字段FieldType必须严格对应. 对应关系如下表:
  

FieldType

实体字段类型

数据库类型

备注

string50

String 或者 枚举

nvarchar(50)

如果是枚举类型, 加上@Enumerated(EnumType.STRING)

string255

String

nvarchar(255)

string512

String

nvarchar(512)

string1024

String

nvarchar(1024)

text

String

nvarchar(MAX)

decimal2

BigDecimal

decimal(14, 2)

decimal3

BigDecimal

decimal(15, 3)

decimal4

BigDecimal

decimal(16, 4)

decimal5

BigDecimal

decimal(17, 5)

decimal6

BigDecimal

decimal(18, 6)

decimal7

BigDecimal

decimal(19, 7)

decimal8

BigDecimal

decimal(20, 8)

decimal9

BigDecimal

decimal(21, 9)

decimal10

BigDecimal

decimal(22, 10)

bool

Boolean

nchar(1)

实体字段加上@Convert(converter = BooleanToYNCharConverter.class)

id

Long

bigint

integer

Integer

int

datetime

LocalDateTime

datetime

date

LocalDate

datetime

version

Long

bigint

由框架维护

blob

Byte[]

varbinary(MAX)

加上@Lob, 强烈建议加上@Basic(fetch = FetchType.lazy)

idRef

Long

bigint

主要用于没有直接建立外键关系, 但需要表达外键的含义的实体字段

codeRef

String

nvarchar(50)

主要用于没有直接建立外键关系, 但需要表达外键的含义的实体字段

- 建议 不要依赖Spring Data的表结构自动生成, 此自动生成机制十分保守, 多数情况下, 对数据库的更改无能为力. 如果, 希望框架能在第一次生成中产生正确的表结构, 那么必须加上@Column(columnDefinition = 'XXX')
- 必须 业务含义上不为空的字段, 在数据库中加上不为空, 在实体字段上加上@Basic(optional = false). 此举是为了提高索引效率

基础代码
Cache的用法

• 必须 不要通过引用相等来判断缓存前后数据的相等与否.
• 建议 Proxy方式下, 内部调用不触发Cache. 所以只在对外的api上附加Cache.
• 建议 @CacheEvict默认情况在方法执行之后清缓存, 如果方法抛出异常, 那么缓存不会清空. 如果无论如何都要清缓存, 加上beforeInvocation=true
  

组件生命周期
canCreate

• 如果路由没有问题,
  

onOpen

-

onActivate

-

onFlush
onRefresh

在Tag页右键菜单点击刷新后出发, 切换抬头后也会触发

canDeactivate
onDeactivate
canClose
onClose
其他

• 会从上游单据中带入的信息, 需要在页面上显示出来.