OA产品开发规范.doc

OA 产品编码开发规 范 目目 录录 第一章 概述第一章 概述 4 4 1 1 目的 4 1 2 范围 4 1 3 文档约定 4 1 4 相关概念及词汇列表 4 1 5 相关角色 5 第二章 协作规范第二章 协作规范 6 6 2 1 参与协作开发 6 2 3 相关规范 6 第三章 设计规范第三章 设计规范 8 8 3 1 JAVA 存放位置 8 3 2 页面存放位置 9 3 3 配置文件存放位置 9 3 4 业务代码位置 10 3 5 数据库设计 10 3 6 MODEL规范 11 3 7 DESIGN配置规范 12 3 8 JAVA 类规范 13 3 9 JAVA 异常规范 14 3 10 JSP 界面规范 14 3 11 PROPERTIES资源文件规范 15 第四章 代码规范第四章 代码规范 1717 4 1 命名规范 17 4 2 风格规范 22 文档授权文档授权 2727 第一章 概述第一章 概述 1 1 目的 目的 对于代码 首要要求是它必须正确 能够按照程序员的真实思想去运行 第二个 的要求是代码必须清晰易懂 使别的程序员能够容易理解代码所进行的实际工作 通过建立开发规范 形成开发小组编码约定 提高程序的可靠性 可读性 可修 改性 可维护性 可继承性和一致性 可以保证程序代码的质量 继承软件开发成果 充分利用资源 使开发人员之间的工作成果可以共享 1 2 范围 范围 1 项目组成员 2 公司相关技术开发人员 3 其他经公司认可的必要知情的人员 1 3 文档约定 文档约定 本文档采用 MS Word2003 软件编写 采用统一风格排版 正文风格为 五号中文宋 体 五号英文 Arial 字体 行距 1 5 行 针对需要重点注意的段落 采用红色描色 一般来说 各章内容相对独立 构成全文的有效组成部分 1 4 相关概念及词汇列表 相关概念及词汇列表 同步代码同步代码 在进行开发的过程中将本地的代码和 SVN 服务器的代码进行同步 在 eclipse 中的操作叫 Synchronize whit Repository 合并代码合并代码 在同步的过程中 发现本地的代码和服务器上的代码都有所改变 这个时候会产生冲突 就需要合并代码 签入签入 在进行开发的过程中将代码放入 SVN 服务器的操作叫签入 check in 在 eclipse 中的操 作叫提交 签出签出 在进行开发的过程中将代码从 SVN 服务器下载下来的操作叫签入 check out 在 eclipse 中的操作叫更新 1 5 相关角色 相关角色 开发人员开发人员 根据开发规范 进行日常开发工作 SVN 管理员管理员 管理 SVN 服务器 包括开通帐号 停止帐号 处理 SVN 遇到的问题 第二章 协作规范第二章 协作规范 开发人员编写程序的过程中 每个程序都会有很多不同的版本 这就需要开发人员很 好的管理代码 在需要的时间可以取出需要的版本 并且每个版本都需要一个完成的说明 和标记 我们公司采用 Sub Version 简称 SVN 主要用于定制项目管理 和 Rational team concert 简称 RTC 主要用于产品管理 做为版本管理工具 在多个开发人员开发同一段 代码的过程中 版本的管理和协作规范显得尤为重要 2 3 相关规范 相关规范 1 开发环境一律使用公司标准开发环境 如使用自己的开发环境 遇到问题则 自己行解决 2 每个开发人员都有自己的帐号和密码 禁止使用其他开发人员的帐号和密码 可以保证每个版本都能找到相应的开发人员 如需开通新帐号密码 请告知 SCM 管理员 3 遇到 SCM 服务器问题 应及时寻找 SCM 管理员帮助解决 避免自己去尝试 解决导致服务器崩溃 4 发现冲突必须经过手动合并后才能上传到 SCM 服务器上 不能将其他开发 人员的代码直接覆盖 导致代码丢失 5 上传的代码必须保证是能运行的代码 不能将未经过测试的代码就上传 SCM 服务器上 导致其他发开人员项目启动不了 6 每天下班前将当天开发的已完成的代码提交到服务器上 7 每天早上来到公司应该同步 SCM 服务器 将最新的代码更新到本地 可以 避免服务器崩溃后找不到最新的代码 第三章 设计规范第三章 设计规范 开发人员在编程过程代码目录结构 业务逻辑在什么地方 配置文件存放位置等 都需要规范 以便其他开发人员快速查找文件 减少开发过程中的沟通 减少维护成 本 3 1 存放位置 存放位置 src 是存放代码的目录 我们公司所有的项目的包名前面都有 com landray kmss 后面接的是项目名称 如 HR 项目就是 com landray kmss hr 下面是 HR 的各个模块 如绩效考核模块 com landray kmss hr pm 我们公司采用三层架构 struts hibernate spring JAVA 代码分成五个目录存 放 目录包括 action form dao model service 还有一个 ApplicationResources properties 资源文件文件 每个模块都包含五个目录和一个资源文 件 代码结构如下 com lanray kmss 项目名称 模块 1 子模块 如归档模块 action constant dao hibernate form model service spring util ApplicationResources properties 模块 2 模块 3 例子 com landray kmss hr pm action com landray kmss hr pm archive 绩效考核归档模块 com landray kmss hr pm dao com landray kmss hr pm dao hibernaete com landray kmss hr pm form com landray kmss hr pm model com landray kmss hr pm service com landray kmss hr pm service spring com landray kmss hr pm ApplicationResources properties 3 2 页面存放位置 页面存放位置 页面文件存放在 WebContent 目录下面 代码结构如下 WebContent 项目名称 模块 1 模块 2 模块 3 例子 WebContent hr pm hr pm action hr pm angle resources 可选 retain salary 发现多个模块使用的文件的直接存放在模块下 resources 存放 JS 图片 样式 静态 HTML 3 3 配置文件存放位置 配置文件存放位置 配置文件名放置路径样例 spring 配置文件WebContent WEB INF KmssConfig sys organization spring xml 枚举类型文件WebContent WEB INF KmssConfig sys organization enums xml 设计信息配置文件WebContent WEB INF KmssConfig sys organization design xml struts 配置文件WebContent WEB INF KmssConfig sys organization struts xml 校验配置文件WebContent WEB INF KmssConfig sys organization validation xml Hibernate 配置文件WebContent WEB INF KmssConfig sys organization hibernate xml design spring xml 等文件应存放 WebContent WEB INF 下的 KmssConfig 目录下 面 代码结构如下 WebContent WEB INF KmssConfig 项目名称 模块 1 data dict 模块 2 例子 WebContent WEB INF KmssConfig hr pm data dict HrPmAction xml design xml spring xml hibernate xml struts xml validation xml enums xml retain 3 4 业务代码位置业务代码位置 业务代码均在 spring 或者 dao 中开发 action 只用于页面的跳转 禁止在 action 写大 量业务代码 禁止对 model 进行赋值操作 禁止多次调用 service 的更新操作 禁止直接调 用 dao 注 开发人员在开发过程中请严格遵循以上代码结构 3 5 数据库设计数据库设计 数据库设计在开发中如有更改 要及时维护 PowerDesigner 没有必要情况不要写数据库特性的 sql 语句 尽量使用 HQL 语句 如有特殊情况特殊 处理 3 6 Model 规范规范 1 model 里面不能使用基础类型 只能使用对象类型 如 double 类型 int 类型等 是不能使用 要使用 Double 类型 Integer 类型等 2 hbm 中 String 的 length 大于 1500 的不能超过 5 个 否则使用 clob 属性 针对类似 Clob Blob 等大字段类型的字段 必须采用字段延时加载的模式 修改样例 如下 hbm 文件 model 类 需实现 net sf cglib transform impl InterceptFieldEnabled 接口 protected String docContent public String getDocContent return String readLazyField docContent docContent public void setDocContent String docContent this docContent String writeLazyField docContent this docContent docContent 3 配置字段索引 命名规则 idx 类名 首字母小写 字段名 注意 以下划线分割 样例如下 注意 注意 主键 外键默认会创建索引 不需要配置 主键 外键默认会创建索引 不需要配置 新增机制 字段新增机制 字段fdModelId fdModelName需要配置索引 需要配置索引 Model实现了实现了ILastModifiedTimeModel接口或者继承接口或者继承LastModifiedTimeModel类 类 fdLastModifiedTime需要配置索引 需要配置索引 样例 List页面按创建时间排序 可以给创建时间配置索引 需要按层级展现或者展现分类下所有文档 可以给层级Id配置索引 建议层级Id 字段长度控制在900以内 联合索引配置 配置的索引名称一样即可 使用较少 例如 fdFirstName和 fdLastName为联合索引 字段多索引配置 多个索引名以逗号分隔 使用较少 例如 fdFirstName和 fdLastName为联合索引 fdFirstName为单字段索引 3 7 Design 配置规范配置规范 design 中配置模块首页 homepage 例如 注意 url 需要转码 并且不能将 s css default 配置在里面 错误的配置 错误的配置 design 中 portlet 配置需要添加 morlUrl 默认配置为模块首页地址 例如 moreURL km doc index 有 我的工作 系统配置 草稿 等属性需要在 design 中配置 myjob config darft 等 treenode 3 8 类规范 类规范 不能使用累赘方法 循环嵌套 循环次数不能超过两次 当出现这样的情况 需要抽取 成方法 增加代码可读性 例如 Public void Test for i 0 i 2 i Test1 Public void Test1 for i 0 i 2 i Test2 Public void Test1 for i 0 i 2 i 错误的写法 Public void Test for i 0 i 2 i for j 0 j 2 j for k 0 k 2 k for 没有使用过的变量需要删除 例如 没有使用过的方法需要删除 已经不需要的代码不要长篇幅的注释放在那里 方法体需要添加注释 3 9 异常规范 异常规范 1 不要在 dao 和 service 层捕获异常 除非特别确定该位置不需要事务处理或则捕获后再 抛出其他类型的异常 但尽量不要这么做 2 自定义异常类型需继承KmssException或KmssRuntimeException 运行时异常 如 protected void trylockHandlerWorkitem WorkflowEngineContext context ISysWfProcessForm form throws KmssException if oprTypes containsKey oprType throw new KmssRuntimeException new KmssMessage sys workflow sysWfWorkitem fdIsDone error 3 在 Action 层必须捕获异常 如 KmssMessages messages new KmssMessages try catch Exception e messages addError e 3 10 JSP 界面规范界面规范 jsp 不允许直接写中文 例如 if fdBeforeStartTimeReminds null fdBeforeStartTimeReminds alert document getElementById fdBeforeStartTimeRemind focus return false 错误的写法 if fdBeforeStartTimeReminds null fdBeforeStartTimeReminds alert 日程开始前提醒的时间不能为空 document getElementById fdBeforeStartTimeRemind focus return false 例如 错误的写法 创建时间 单选按钮或多选按钮需要添加标签 如 是 否 jsp 中需要 import 一个 jsp 时需要在 import 中指定编码格式 UTF 8 避免出现乱码问 题 例如 js 中 alert 使用的资源文件中若含有双引号 alert 必须使用单引号 例如 km doc subject 当前操作为 修改当前处理人 alert 错误的写法 alert 3 11 properties 资源文件规范资源文件规范 properties 不允许写入含有单引号或双引号的 html 语句 如必要资源文件需拆语句 例如 资源文件中 sysNotifyTodo home you 您 sysNotifyTodo home notHave 没有 sysNotifyTodo home todo 待办事宜 jsp 中 错误的写法 资源文件中 sysNotifyTodo home havenot 您没有 待办事宜 jsp 中 第四章 代码规范第四章 代码规范 4 1 命名规范 命名规范 1 数据库设计数据库设计 表和字段全部小写 用 分隔表名或字段名中的多个词 表 产品简称 模块简称 表简称 样例 hr org dept 每个数据库的主表 表 产品简称 模块简称 main 样例 km review main 子表名称 产品简称 模块简称 主表简称 子表简称 样例 km review main keyword 中间表名称 产品简称 模块简称 主表简称 字段简称 样例 km review main post 主键 fd id 外键 fd 字段名 id 样例 fd creator id 字段 fd 字段名 样例 fd order 字段类型 主外键 VARCHAR2 36 布尔 NUMBER 1 枚举 NUMBER 2 普通的多行文本 VARCHAR2 1500 或 VARCHAR2 2000 RTF CLOB 排序号 NUMBER 10 注 表名长度 字段名长度均不能超过 30 个字符 2 JAVA 类类 类名 产品简称 模块简称 表内容简称 样例 HrOrgDept 普通属性 fd 字段名 样例 fdOrder docCreator 特殊对象属性 直接属性的类名 首字母小写 说明 特殊对象指该对象通过类名已经可以明确对象的含义 该对象无二义 性 如 hrOrgPostType 岗位性质 但类似 SysOrgElement 组织架构元素 的对象 它既可以表示创建者 也可以表示修改者或其他实际的业务属性 这种情况下 该对象必须以 普通属性 的格式命名 如创建者命名为 fdCreator 样例 hrOrgPostType 普通列表属性 fd 字段名的复数 样例 fdEditors 特殊列表属性 直接属性的类名的复数 说明 特殊列表属性类似于特殊对象属性 与普通列表属性的区别是该类含 义无二义性 样例 hrOrgPostTypes 3 常用表名字常用表名字 含义含义表名表名样例样例备注备注 模板 类别中间表 产品简称 模块简称 tmp category km review tmp category如果有多种模 板则根据需要 修改单词 tmp 相关岗位中间表 产品简称 模块简称 主表简称 post km review main post 相关属性中间表 产品简称 模块简称 主表简称 property km review main property 关键字中间表 产品简称 模块简称 主表简称 keyword km review main keyword 管理员中间表 产品简称 模块简称 主表简称 admin km review main admin 可阅读者 可使用者 中间表 产品简称 模块简称 主表简称 reader km review main reader 可编辑者 可维护者 中间表 产品简称 模块简称 主表简称 editor km review main editor 其他可阅读者 产品简称 模块简称 主表简称 oreader km review main oreader 其他可编辑者 产品简称 模块简称 主表简称 oeditor km review main oeditor 所有可阅读者 产品简称 模块简称 主表简称 areader km review main areader 所有可编辑者 产品简称 模块简称 主表简称 aeditor km review main aeditor 附件可拷贝者 产品简称 模块简称 主表简称 attcopy km review main attcopy 附件可下载者 产品简称 模块简称 主表简称km review main attdl attdl 附件可打印者 产品简称 模块简称 主表简称 attprint km review main attprint 4 常用字段常用字段 普通类型 含义含义字段名字段名Java 属性名属性名数据库字段类型数据库字段类型Java 字段类型字段类型必须必须 名称fd namefdNameVARCHAR2 200 StringY 排序号fd orderfdOrderNUMBER 10 Integer 描述fd descriptionfdDescriptionVARCHAR2 150 0 String 父类别fd parent idhbmParentVARCHAR2 36 IbaseTreeModel 所属部门fd dept idfdDeptVARCHAR2 36 SysOrgElement 通知类型fd notify typefdNotifyTypeVARCHAR2 100 String 内容管理 含义含义字段名字段名Java 属性名属性名数据库字段类型数据库字段类型Java 字段类型字段类型必须必须 标题doc subjectdocSubjectVARCHAR2 200 StringY 状态doc statusdocStatusVARCHAR2 2 String 创建者doc creator iddocCreatorVARCHAR2 36 SysOrgPersonY 修改人doc alteror iddocAlterorVARCHAR2 36 SysOrgPerson 作者doc author iddocAuthorVARCHAR2 36 SysOrgPerson 创建时间doc create timedocCreateTimeDATEDateY 最后修改时 间 doc alter timedocAlterTimeDATEDate 发布时间doc publish timedocPublishTimeDATEDate 所属分类doc category iddocCategoryVARCHAR2 36 ISysCategoryTempl ate Y 所属部门doc dept iddocDeptVARCHAR2 36 SysOrgElement 关键字doc keyworddocKeywordVARCHAR2 200 String 相关岗位doc post iddocPosts VARCHAR2 36 中间表 List 相关属性doc property iddocProperties VARCHAR2 36 中间表 List 点击率doc hitsdocHitsNUMBER 10 Integer 文档内容doc contentdocContentCLOBString 权限相关 含义含义字段名字段名Java 属性名属性名数据库字段类型数据库字段类型Java 字段类型字段类型必须必须 管理员auth admin idauthAdmins VARCHAR2 36 中间表 List 可阅读者auth reader idauthReaders List VARCHAR2 36 中间表 可编辑者auth editor idauthEditors VARCHAR2 36 中间表 List 其他可阅读 者 auth other reader idauthOtherRea ders VARCHAR2 36 中间表 List 其他可编辑 者 auth other editor idauthOtherEdit ors VARCHAR2 36 中间表 List 所有可阅读 者 auth all reader idauthAllReade rs VARCHAR2 36 中间表 List 所有可编辑 者 auth all editor idauthAllEditor s VARCHAR2 36 中间表 List 所有人可阅 读标记 auth reader flagauthReaderFl ag NUMBER 1 Boolean 所有人可编 辑标记 auth editor flagauthEditorFla g NUMBER 1 Boolean 附件可拷贝 者 auth att copy idauthAttCopys VARCHAR2 36 中间表 List 不可拷贝标 记 auth att nocopyauthAttNocop y NUMBER 1 Boolean 附件可下载 者 auth att download idauthAttDownl oads VARCHAR2 36 中间表 List 不可下载标 记 auth att nodownloadauthAttNodo wnload NUMBER 1 Boolean 附件可打印 者 auth att print idauthAttPrints VARCHAR2 36 中间表 List 不可打印标 记 auth att noprintauthAttNopri nt NUMBER 1 Boolean 注 创建人 创建时间必须为 docCreator 和 docCreateTime 5 常用枚举常用枚举 字段名称值列表备注 doc status 文档状态 10 草稿 20 待审 11 驳回 00 废弃 30 发布 40 过期 该状态可选 如果同等状态下有多种 形式的 请修改第二位 的编码 如发布状态下 也会有已反馈等 可将 其置为 31 6 权限命名权限命名 a 每个模块必须定义 DEFAULT 的角色 用于校验模块中未声明的页面以及操 作权限 并在该角色的注释中说明 DEFAULT 所具有的操作权限 b 模块的基础配置信息 简单配置 如员工管理中的政治面貌 学历等 若无 特别业务要求 均采用集中一个角色的方案进行配置 c 模块中稍微复杂的配置 如 员工信息中的异动流程设置 采用一个角色对 应一种配置的方案进行配置 d 一般的主业务的配置 需要针对 新增 删除 修改 查阅 等操作分别进行 配置 其中查阅和修改操作 针对是否有数据过滤 又分为读者 作者 有数 据过滤 和阅读 修改 无数据过滤 两种方式设置 对于有数据过滤的模块 不限制 list 操作 e 对于组织架构关联很大的主业务的配置 需要进行本部门下的新增 删除 修改 权限控制 对于阅读的权限 采用数据过滤的方式 过滤掉非本部门的数据 同样不限制 list 操作 默认角色 ROLE 模块名 英文 DEFAULT 定义于 模块的默认校验 名称 模块名 中文 默认权限 描述 可访问模块名 中文 中的其他页面以及可以进行模块名 中文 中的其他操作 样例 角色 ROLE SYSORG DEFAULT 名称 组织架构 默认权限 描述 可访问组织架构中的其他页面以及可以进行组织架构中的其他操作 基础信息维护者 ROLE 模块名 英文 SETTING 定义于 简单的基础信息维护 注意 简单的基础信息一般指单表 名称 模块名 中文 维护基础信息 描述 可维护模块名 中文 中的基础信息 样例 角色 ROLE SYSORG SETTING 名称 组织架构 维护基础信息 描述 可维护组织架构中的基础信息 新增角色 ROLE 表名 英文 CREATE 定义于 表的 add save saveadd 页面 名称 模块名 中文 新增表名 中文 描述 可新增模块名 中文 中的表名 中文 信息 样例 角色 ROLE SYSORGDEPT CREATE 名称 组织架构 新增部门 描述 可新增组织架构中的部门信息 删除角色 ROLE 表名 英文 DELETE 定义于 表的 delete deleteall 页面 名称 模块名 中文 删除表名 中文 描述 可删除模块名 中文 中的表名 中文 信息 样例 角色 ROLE SYSORGDEPT DELETE 名称 组织架构 删除部门 描述 可删除组织架构中的部门信息 查阅角色 ROLE 表名 英文 VIEW 定义于 表的 view 和 list 页面 注意跟 READER 的角色区分 一般用于无权限过滤的表 名称 模块名 中文 查阅表名 中文 描述 可查阅模块名 中文 中的表名 中文 信息 样例 角色 ROLE SYSORGDEPT VIEW 名称 组织架构 查阅部门 描述 可查阅组织架构中的部门信息 编辑角色 ROLE 表名 英文 EDIT 定义于 表的 edit 和 update 页面 注意跟 EDITOR 的角色区分 一般用于无权限过滤的表 名称 模块名 中文 编辑表名 中文 描述 可编辑模块名 中文 中的表名 中文 信息 样例 角色 ROLE SYSORGDEPT EDIT 名称 组织架构 编辑部门 描述 可编辑组织架构中的部门信息 读者角色 ROLE 表名 英文 READER 定义于 表 Model 的数据过滤器 一般用于有权限过滤的表 名称 模块名 中文 查看所有的表名 中文 描述 可查看模块名 中文 中的所有表名 中文 信息 无论是否有授权 样例 角色 ROLE SYSORGDEPT READER 名称 组织架构 查看所有的部门 描述 可查看组织架构中的所有部门信息 无论是否有授权 读者角色 ROLE 表名 英文 EDITOR 定义于 表 Model 的数据过滤器 一般用于有权限过滤的表 名称 模块名 中文 编辑所有的表名 中文 描述 可编辑模块名 中文 中的所有表名 中文 信息 无论是否有授权 样例 角色 ROLE SYSORGDEPT EDITOR 名称 组织架构 编辑所有的部门 描述 可编辑组织架构中的所有部门信息 无论是否有授权 结合部门的角色 ROLE 表名 英文 DEPT OPT 定义于 表的 OPT 相关页面 名称 模块名 中文 操作名本部门下的表名 中文 描述 可操作名模块名 中文 中本部门下的表名 中文 信息 样例 角色 ROLE SYSORGDEPT DEPT ADD 名称 组织架构 增加本部门下的部门 描述 可增加组织架构中本部门下的部门信息 4 2 风格规范 风格规范 1 基本要求基本要求 程序结构清析 简单易懂 单个函数的程序行数避免超过 100 行 单个类避 免超过 1000 行 尽量使用标准库函数和公共函数 不要随意定义全局变量 尽量使用局部变量 使用括号以避免二义性 如 if 和 else 基础数据对象如 Long Double 等不能使用 new 方法直接初始化 要使用 ValueOf 方法 集合类要声明集合元素的类型 如 Map map new HashMap 2 文件组织文件组织 Java 源文件还遵循以下规则 1 1 包和引入语句 Package and Import Statements 在多数 Java 源文件中 第一个非注释行是包语句 在它之后可以跟引入 语句 例如 package mon actions import java util Map import javax servlet ServletException import javax servlet http HttpServletRequest import org apache struts action ActionMapping 1 2 文件注释 Beginning Comments 所有的源文件都应该在有一个 C 语言风格的注释 其中列出该类的使用说 明 作者 版本信息 日期 Action基类 不建议直接继承 仅当ExtendAction完全无法满足实际业务 需求时才继承该类 使用范围 Action层代码 作为基类继承 author 叶中奇 version 1 0 2006 04 02 3 注释注释 在处理过程的每个阶段都有相关注释说明 特殊变量 结构 联合 类 或对象 定义或引用时 也应写注释 有注释有便于其他开发人员或自己下 次查看代码时候能很明白程序的意思 读懂程序 可以减少内部的沟通 程序可以有 4 种实现注释的风格 块 block 单行 single line 尾端 trailing 和行末 end of line 1 块注释 Block Comments 块注释通常用于提供对文件 方法 数据结构和算法的描述 块注释被 置于每个文件的开始处以及每个方法之前 它们也可以被用于其他地方 比 如方法内部 在功能和方法内部的块注释应该和它们所描述的代码具有一样 的缩进格式 块注释之首应该有一个空行 用于把块注释和代码分割开来 比如 Here is a block comment 2 单行注释 Single Line Comments 短注释可以显示在一行内 并与其后的代码具有一样的缩进层级 如果 一个注释不能在一行内写完 就该采用块注释 参见 块注释 单行注释之前 应该有一个空行 以下是一个 Java 代码中单行注释的例子 if condition Handle the condition 3 尾端注释 Trailing Comments 极短的注释可以与它们所要描述的代码位于同一行 但是应该有足够的 空白来分开代码和注释 若有多个短注释出现于大