JeeSite 快速开发平台
官方网站
    • 平台简介
    • 架构特点
    • 技术选型
    • 功能介绍
    • 安装部署
    • 常见问题
    • 目录结构
    • 更新日志
    • Vue 文档
    • BPM 文档
    • Cloud 文档
V4 演示
Vue 演示
💖联系
  • 我要提意见、文档纠错
  • JeeSite 代码库, 请⭐Star关注
  • JeeSite Vue 代码库, 请⭐关注
  • Spring Cloud 微服务架构
  • JeeSite 手机端/移动端
  • Flowable 中国式工作流
  • OAauth2 统一认证服务器
  • 政务内外网环境中间件
  • 访问 ThinkGem 官方博客
  • 点击进入,下拉查看动态
官方网站
    • 平台简介
    • 架构特点
    • 技术选型
    • 功能介绍
    • 安装部署
    • 常见问题
    • 目录结构
    • 更新日志
    • Vue 文档
    • BPM 文档
    • Cloud 文档
V4 演示
Vue 演示
💖联系
  • 我要提意见、文档纠错
  • JeeSite 代码库, 请⭐Star关注
  • JeeSite Vue 代码库, 请⭐关注
  • Spring Cloud 微服务架构
  • JeeSite 手机端/移动端
  • Flowable 中国式工作流
  • OAauth2 统一认证服务器
  • 政务内外网环境中间件
  • 访问 ThinkGem 官方博客
  • 点击进入,下拉查看动态
  • 快速了解

    • 平台简介
    • 架构特点
    • 技术选型
    • 功能介绍
    • 开发规范
      • 一、用户界面
        • 1、设计原则
        • 2、数据列表
        • 3、编辑表单
      • 二、数据库设计规范
        • 1、命名规范
        • 2、设计规范
        • 3、使用规范
        • 4、数据库设计
      • 三、平台开发规范
        • 1、JeeSite 包的命名规范
        • 2、JeeSite 分层命名规范
        • 3、JeeSite 视图文件规范
        • 4、JeeSite 静态文件规范
        • 5、Vue 分离端目录规范
      • 四、其它开发规范
    • 目录结构
    • 树表设计
    • 更新日志 🚀
  • 开发手册

  • Vue 开发手册

  • 扩展功能专题

  • 云服务技术架构

  • 技术服务与支持

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

# 一、用户界面

# 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端图标及标题内容显示不全的,应尽量减少文字,不显示…,让文字显示全

# 3)Vue 分离版设计

  • 共享 Ant Design of React (opens new window) 设计工具体系。
  • 提炼自企业级中后台产品的交互语言和视觉风格。

# 二、数据库设计规范

# 1、命名规范

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

# 2、设计规范

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

# 3、使用规范

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

# 4、数据库设计

JeeSite核心模块数据库设计 ER 图

# 三、平台开发规范

# 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类名、映射路径、方法名、视图文件名,举例如下:

类型 命名 说明
类名 SysEmpUserController.java 系统模块可不加 Sys
映射路径 /sys/empUser/list /模块[/子模块]/功能/操作
映射方法 public list() {} 功能名,如列表:list,列表数据:listData,表单:form
视图文件名 empUserList.html 不要直接命名为 list.html(写全方便查找)
视图文件路径 /src/main/resources/views/modules/sys/empUser/ 统一放 resources 资源目录下
Vue视图命名 /src/views/sys/empUser/list.vue 与映射路径一致

遵循一定的命名规范,可快速根据映射路径找到对应的源代码。

# Service

操作 命名 备注
类名 以Service结尾 继承 CrudService,TreeService,QueryService
查询一条数据 get 以 get 开头
插入数据 insert 以 insert 开头
更新数据 update 以 update 开头
新增或编辑 save 以 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,查看文档 (opens new window)
注解位置 依据能写 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/组件文件包

# 5、Vue 分离端目录规范

点我跳转到 Vue 分离端目录结构

# 四、其它开发规范

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

进入 JeeSite 源码仓库页面,点击右上角 ⭐ Star 加星关注。

← 功能介绍 目录结构→

联系我们:s.jeesite.com  |  微信号:jeesitex  |  邮箱:jeesite@163.com
© 2013-2023 济南卓源软件有限公司 版权所有 | Theme Vdoing

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

  • 跟随系统
  • 浅色模式
  • 深色模式
  • 阅读模式