JeeSite 4.x

Spring Boot 最好的快速开发平台

开发规范、设计原则、数据库规范、平台规范

一、用户界面

1、设计原则

1)对齐

  • 层次结构清晰,观察 1 像素,引导视觉流向,让用户更流畅地接收信息
  • 如果页面的字段或段落较短、较散时,需要确定一个统一的视觉起点

2)多元化

  • 根据不同的用户体验,可快速进行界面色调切换
  • 点击侧边栏头像,扩大工作区域显示,可快速折叠侧边栏和顶部导航栏
  • 根据用户喜好,可折叠侧边栏,默认折叠侧边栏,取消页签模式,表单弹窗模式
  • 弹窗的表单,关闭表单后,自动刷新列表数据,保留列表查询条件
  • 列表操作体验清晰,不太实用的操作进行折叠隐藏
  • 列表查询区域隐藏,扩大列表显示区域

3)布局色彩

  • 响应式样式,12 列栅格化布局,根据屏幕大小进行自适应布局,支持平板或手机操作
  • 色彩源于『自然』的设计价值观,设计师通过对自然场景的抽象捕捉

4)导航设计

  • 在广义上,任何告知用户他在哪里,他能去什么地方以及如何到达那里的方式,都可以称之为导航
  • 支持侧边栏全部导航;或者顶部一级导航,二级以下导航在侧边栏

2、数据列表

1)列对齐方式

  • 短小字符居中,比较长的字符居左,日期居中,货币或带小数点的数字居右
  • 数值位数相等的字段,如:编码、编号:居中
  • 字典类,如:分类、类型、类别、状态:居中
  • 不规则长度,5个字符以上,名称、标题:居左
  • 日期时间:居中
  • 与货币相关的,金额、单价:居右
  • 带小数点的数字,数量、百分数:居右
  • 整数型数字,年龄,个数:居中
  • 合计,与合计列对齐方式相同

2)列显示格式

  • 与货币相关,金额或单价:保留两位小数,如无特殊要求,不加货币符号,不使用千分位符号,默认单位“元”,如果单位不是“元”,则必须在列标题或当前页标明单位,如:金额(万元)
  • 长字符列,名称、标题、备注等:当列宽不足时,用 … 号表示无法显示的字符
  • 日期:yyyy-MM-dd,日期时间:yyyy-MM-dd HH:mm,如业务无特别要求,不带秒,如需要时分秒,格式为: yyyy-MM-dd HH:mm:ss 采用24小时制
  • 列宽要适中,根据内容调整列宽大小

3)其他要求

  • 列表中存在与金额相关的列,或者与数量相关的列,根据业务要求,列表底部增加合计,如果列表是分页列表,合计默认为查询结果的合计,而不是当前页合计
  • 合计校验:明细行合计值,与合计行值相同,不要出现明细与合计的数值不对的情况
  • 汇总与明细校验:汇总值与钻取的明细合计值相同,同上
  • 根据业务要求,比较大或比较耗时的页面,第一次打开时,如没有特殊要求,默认不执行查询显示数据,需要点击查询,执行显示数据,并提示“点击查询显示数据”信息
  • 对于列与数字相关的,如:金额、数量、证件号码(如:身份证)或其它由长数字组成的字段,不能出现科学计数法格式
  • 明细行中不能存在重复记录

4)查询条件

  • 数据字典字段作为查询条件,无特殊要求,信息内容相对固定少于20行时,采用下拉选择方式,否则采用弹出对话框选择方式;有特别要求时,可以采用输入方式,进行模糊查询,除此之外,必须采用选择方式
  • 查询条件为多行时,标签需要上下两端对齐,标签单行右对齐,注意美观
  • 输入框或选择框,上下两端对齐,宽度适中

3、编辑表单

1)表单控件

  • 必填信息,必须明确区分,标签前增加红色星号,醒目显示,必填信息在保存时必须增加必填验证
  • 数值类型,必须增加数值验证
  • 日期类型,必须增加日期格式验证
  • 边界验证,录入信息的长度不得多于数据库字段长度,input标签必须包含增加maxlength属性
  • 无特殊情况,如:电话、身份证、邮箱,能用正则表达式验证的字段必须启用验证
  • 界面录入信息与列表显示信息保持一致,避免字段张冠李戴
  • 界面显示信息与数字相关的,如:金额、数量、证件号码(如:身份证)或其它由长数字组成的字段,不能出现科学计数法格式
  • 必须避免提交类型按钮多次执行,出现多条相同信息,在未成功之前,不能多次点击

2)其它要求

  • 对整个项目进行跨浏览器的测试(必须兼容IE9+、360、Chrome、Firefox浏览器)
  • 界面大小应该适合美学观点,感觉协调舒适,能在有效的范围内吸引用户的注意力,注意细节(观察1像素距离、列表文字对齐)
  • 必须保证在最小分辨率1024x768的可视性(不允许错版),在高分辨率下页面要自适应,不能出现标题背景空白,错位情况
  • 每一步操作,如保存、更新、审核,都要有提示,如:保存xx成功!
  • 检查界面是否有文字错误,避免出现看不懂的文字
  • 手机端或PC端图标及标题内容显示不全的,应尽量减少文字,不显示…,让文字显示全

二、数据库设计规范

1、命名规范

  • 数据库对象,如:表、列、索引、视图、存储过程、自定义函数,的命名的原则是简、短,易懂好记,有意义的英文单词、常用缩写,多个单词组成的,当长度比较大时应使用缩写,特殊情况使用拼音或首字母
  • 数据表命名:必须带有模块前缀,如财务总账:js_fin_
  • 如果命名由多个词汇组成,词汇之间加 _ 下划线,如:js_sys_office_company

2、设计规范

  • 通常情况下每张表必须有主键,对于非主键,具有唯一性质的,必须加,唯一索引
  • 每张表,每个字段都必须有正确的中文描述说明,以便快速生成数据字典
  • 业务数据表必要时冗余基础信息表的核心字段,如:部门编码、部门名称,需要成对出现在业务数据表中
  • 对于字符类型(VERCHAR)字段,确定数据值仅是数字、字母并无其它特殊字符的情况下使用VERCHAR字段,其它必须使用NVARCHAR类型,避免使用VARCHAR类型
  • 表字段的长度要统一,尤其基础数据在业务数据中的引用,如:部门编码、部门名称,在任何业务数据表中的长度务必保持一致
  • 存储过程、自定义函数、视图,以及调度,必须要有详细的注释说明
  • 统一入口,统一出口原则:相同意义的数据存储、提取,使用同一过程和方法
  • 不要盲目的加入其他索引,根据需要统一加索引

3、使用规范

  • 在指定用户下,只有项目经理具有数据表对象的设计权限,其他开发人员不得调整表结构
  • 作业调度需要有详细的登记台账(也是项目管理要求的一部分)
  • SQL书写采用:关键字大写,表名,列名小写
  • 变更数据库必须同步 erm 模型

三、平台开发规范

1、JeeSite 包的命名规范

设有公司统一报名如:com.jeesite 包,不允许直接在此包下直接建立模块,要先创建一个 modules 包。

  • 模块格式:com.jeesite.modules.模块名.分层.子模块名.功能类
    • 分层为 entity、dao、service、web、utils、config
    • 若模块下只有几个功能,没有子模块,就不需要再建立子模块了
  • Spring Boot 自动配置文件格式:com.jeesite.autoconfigure.模块名.配置类
    • 自动配置的类,在 META-INF/spring.factories 里指定
  • 通用封装包或工具类:com.jeesite.common.大类.小类.封装类

2、JeeSite 分层命名规范

Controller

操作 命名 备注
类名 以Controller结尾,继承BaseController UserController
类上的映射路径 ${adminPath} /模块/子模块/功能 ${adminPath}/sys/user
自动注入属性 与注入名相同,不允许注入Dao @Autowired
方法上的映射路径 与方法名相同 @RequestMapping
方法上的权限字符串 模块名:子模块名:控制器名:功能名 @RequiresPermissions
每次请求都会执行的方法 get @ModelAttribute
列表页面 list  
列表数据 listData  
新增或编辑表单 form  
新增或编辑提交地址 save  
删除 delete  
停用 disable  
启用 enable  
主键校验 check开头  
导入 import开头  
导出 export开头  
树结构数据 treeData  

四名保持命名联系: Controller类名、映射路径、方法名、视图文件名,举例如下:

类名 SysUserController.java 系统模块可不加 sys
映射路径 /sys/user/list /模块[/子模块]/功能/操作
映射方法 public list() {} 功能名,如列表:list,列表数据:listData,表单:form
视图文件名 userList.html 不要直接命名为 list.html
视图文件路径 /WEB-INF/views/modules/sys/user/  

Service

操作 命名 备注
类名 以Service结尾 继承 CrudService,TreeService,QueryService
查询一条数据 get 以 get 开头
插入数据 insert 以 insert 开头
更新数据 update 以 update 开头
新增或编辑 save  
删除 delete 以 delete 开头
查询多条数据 findList 以 find 开头
查询多条分页 findPage 以 find 开头

Dao

操作 命名 备注
类名 以Dao结尾 继承 CrudDao,TreeDao,QueryDao
查询一条数据 get 以 get 开头
插入数据 insert 以 insert 开头
更新数据 update 以 update 开头
删除 delete 以 delete 开头
物理删除 phyDelete  
查询多条数据 findList 以 find 开头  

Entity

操作 命名 备注
类名 根据表名以驼峰命名法转换 继承 DataEntity,TreeEntity,BaseEntity
主键 @Column(isPk=true) 指定主键的列会自动与 getId() setId() 绑定
验证方法 Hibernate Validator 例如:@Length,@NotNull,查看文档
注解位置 依据能写 get 方法上绝不写字段上原则  
父类中已有的属性 父类中已有的属性无需定义,特殊情况除外  
非表属性的字段 如查询字段,必须写清楚注释说明用途。  

3、JeeSite 视图文件规范

所有视图文件均放在:模块项目/src/main/resources/views 目录下,尽量不放在web项目下,约束如下:

include 公共视图代码块
layouts 公共视图布局文件
modules 功能模块视图文件,格式:/modules/模块名[/子模块]/功能页面
themes 个性化主题视图文件存放路径,格式:/themes/modules/模块名[/子模块]/功能页面

4、JeeSite 静态文件规范

所有静态文件均放在:模块项目/src/main/resources/static 目录下,尽量不放在web项目下,约束如下:

common 存放公共脚本,不建议项目使用过程中修改。
modules 项目相关的模块 js 和 css 文件存放位置,格式:/modules/模块名[/子模块]/静态文件
themes 个性化主题视图文件存放路径,格式:/themes/modules/模块名[/子模块]/静态文件
组件文件 格式:组件名/组件版本/组件文件,例如:/static/echarts/4.2/组件文件包

四、其它开发规范

主键:有意义的,有规则的数据必须采用手动编码方式,不允许使用 UUID 自动生成注解表示,方便运维,例如:组织机构编码,区域编码

关注 JeeSite 公众号,了解最新动态