应用系统开发规范V10.doc

重庆农商行信贷管理系统开发规范重庆农商行信贷管理系统项目组2010-09目录1.概述5系统技术框架5概述5图例6平台与业务组件接口设计72.代码开发规范102.1.命名规范102.1.1.应用目录结构规范102.1.2.包结构与命名102.1.3.类/接口命名142.1.4.成员变量及方法命名152.1.5.局部变量命名（及声明）152.2.代码书写规范162.2.1.总体原则162.2.2.类/接口定义162.2.3.文本格式172.3.注释规范182.3.1.程序注释182.3.2.文档注释（JavaDoc）192.4.内容规范202.4.1.toString202.4.2.Log202.4.3.文件编码212.5.JSP页面编码212.6.包结构定义222.7.业务实体类（DOMAIN）编码222.8.操作类（Operation）编码222.9.组件类（Component）编码232.10.组件代理类（Agent）编码231.1.组件接口实现类（Interface）编码241.2.组件异常类（Exception）编码248.开发项命名规则258.1.文件命名258.2.标签命名259.开发活动规范259.1.小组同步25文档信息文档版本编号:文档版本日期:起草人:况杰起草日期:2010-9-6版本记录版本编号版本日期创建/修改说明1.02010-9-6况杰起草1. 概述本文档用于定义“重庆农商行信贷管理系统项目”中的源代码开发规范以及其他开发项的命名规则，并且对日常开发活动进行规范，以提高工作效率，保证工作质量。系统技术框架概述 利用EMP的IOC功能统一配置文件 使用定义的数据库联接统一数据库连接 统一技术框架，根据项目情况采用如下两种方式n MVC +业务组件+ 表模型n MVC +业务组件+JDBC业务组件(BIZ COMPONENT)结构DOMAIN:业务实体的VO，用于存储业务实体数据，贯穿EMP的OPERATION，业务组件的COMONET，AGENT，DAO层。COMONENT：具体实现业务逻辑的JAVABEAN，调用AGENT，并被EMP的OPERATION调用。AGENT：主要调用DAO及其他资源API（如通讯组件等）。DAO：由EMP提供的数据库访问对象。INTERFACE：业务组件间组件统一对外接口。图例平台与业务组件接口设计系统层次划分为便于清晰地划分支撑平台功能、技术实现与业务逻辑，下图结合支撑平台与业务组件将整个系统从功能结构上分为四个层次。界面层: 为用户与系统的接口，其使用EMP IDE工具生成主体页面代码，开发人员可适当调整，并使用js对界面要素进行访问与操作，在这一层负责界面逻辑的处理。接入层: 为EMP基础支撑平台与业务逻辑功能接口（既平台调用业务逻辑的入口），其由EMP容器提供（使用EMP MVC实现对界面HTTP请求的响应，在对应的Operation中调用业务逻辑），在这一层负责一笔业务交易的完整处理（同一事务），以及平台与业务组件间的数据格式转换等基础的功能。业务逻辑层：以业务组件为基本单元来完成各类不同的业务需求，其由各个业务组件组成，在这一层负责各个业务逻辑、业务流程处理的实现，但不宜包含技术细节，技术细节应屏蔽在技术实现层中。技术实现层：为组件中业务逻辑的具体实现，其由各个业务代理组件，在这一层负责完成所有的技术细节，例如调用表模型提供的TableModelDAO中的通用功能。业务组件结构对业务功能将以两个次层进行划分业务组件 与 业务构件，业务组件，作为业务功能划分基本单元，其由若干个业务代理来实现；多个相关的业务组件组成一个业务构件，业务构件作为最顶层的业务划分。例如下图所示，客户构件内，有若干个业务组件。业务构件将对应代码中的包这一层，而业务组件与业务代理对应完成业务处理类。业务构件：是组件的集合，用于对同一类有内在联系的业务组件的包装，负责与其它业务模块之间的边界化分，其物理介质对应一个文件目录与一个构件配置文件。业务组件：是业务逻辑的基本单元，用于对同一类业务逻辑的包装，负责业务功能之间的边界化分，其物理介质对应一个java类文件（所有业务组件需继承CMISComponent类）。业务代理：代理业务组件完成具体的技术实现细节，其物理介质对应一个java类文件（所有业务代理需继承CMISAgent类）。配置文件：作为构件内的所有的业务组件与业务代理的配置存储介质，格式如下： . . . . 注：在该构件配置文件中，$xxx1 $xxx2表示属性的键名支撑平台与业务组件间接口实现描述对于普通的Web应用系统，在EMP支撑平台中是通过配置MVC中的Action实现接入，并在Operation中调用后台的业务组件，在业务组件中调用业务代理，在业务代理中调用底层的技术组件。下面类图中描述了业务组件类与平台技术组件内之间关系。如上图所示，所有业务组件均通过Operation中被使用方调用，由ComponentFactory实例化某个（某几个）具体的业务组件，而所有组件必须继承CMISComponent；在业务组件中调用业务代理，在业务组件的父类中使用AgentFactory来实例化某个（某几个）具体的业务代理（通过组件父类中的getAgentInstance方法），而所有代理必须继承CMISAgent; 在CMISComponent、CMISAgent两个父类中包含EMP的Context，但对于业务组件内其不可见，也不许使用，在实现业务逻辑时，若需要使用平台技术组件功能，则使用父类的getConnection、getTableModelDAO等方法实现。ComponentHelper类为组件的工具类，现负责提供平台数据结构与业务组件数据结构之间的专换功能。组件间调用约束1、 调用基本规则是在系统四个层次中，上层资源中可以调下层资源，而不能反向，同层之间需经过接口才能相互调用2、 Operation可以通过调用仍何业务组件（通过ComponentFactory实例化），业务组件中可以调用所在构件中的任意业务代理，而不能调用其他构件中的业务代理（通过构件的配置文件来实现该约束）3、 跨构件之间的组件间调用，需通过接口实现调用，构件之内的组件间调用不作该约束，但建议尽可能通过接口实现调用。4、 跨构件之间的业务代理不能相互调用，构件之内的业务代理不作该约束，但建议尽可能业务代理间相互不调用。2. 代码开发规范2.1. 命名规范2.1.1. 应用目录结构规范l 图像、JS、CSS等对安全性要求不高的文件直接放在应用根目录下，以便于引用，例如：/应用根目录/images下存放所有的图像、/应用根目录/scripts放所有JS脚本、/应用根目录/styles下存放所有的样式l 类文件、JSP、各配置文件等安全性要求高的文件放在/应用根目录/WEB-INF下，便于作访问控制，例如：/应用根目录/WEB-INF/mvcs/CMISMvc下存放jspl /应用根目录/scripts下除EMP提供的JS之外，对于与信贷业务相关的JS，均放在/应用根目录/scripts/cmis/中，并且按组件再细分目录（例如，/应用根目录/scripts/cmis/CUS、/应用根目录/scripts/cmis/PUB）l /应用根目录/WEB-INF/mvcs/CMISMvc下，一般分两级子目录，第一级是按业务组件分，其存放该业务相关的所有JSP，第二级按业务表名分，其存放表模型自动为生成的JSPl permission/client下存放 每个用户的界面权限文件，而permission所在目录由系统配置决定。2.1.2. 包结构与命名 信贷管理系统的包名统一由com.yucheng.cmis为起始，第四级包为与信贷业务相关的业务组件与技术组件，若业务组件需进一步划分，则可使用第五、第六级包名。包名不要超过六级。包名中的英文全部使用小写字母。 组件包名以组件英文名缩写为准例如：客户管理组件包名：com.yucheng.cmis.cus. 规范细则 DOMIAN它是贯穿其它三个层次的基础,主要是定义要参与的数据对象,并将其封装成类.存放目录如下.comyuchengcmisbizcomponentnamesubbizcomponentname.domain注：bizcomponentname：业务组件名称。如：cussubbizcomponentname：子业务组件名称。如：cuscom. :更深层次的子组件名例子：.comyuchengcmiscuscuscomdomain(com.yucheng.cmis.cus.cuscom.domain) OPERATION.comyuchengcmisbizcomponentnameop注：bizcomponentname：业务组件名称。如：cus. :更深层次的子组件名例子：.comyuchengcmiscusop(com.yucheng.cmis.cus.op) COMPONETponent注：bizcomponentname：业务组件名称。如：cussubbizcomponentname：子业务组件名称。如：cuscom. :更深层次的子组件名例子：.comyuchengcmiscuscuscomcomponent(ponent) AGENT.comyuchengcmisbizcomponentnamesubbizcomponentname.agent注：bizcomponentname：业务组件名称。如：cussubbizcomponentname：子业务组件名称。如：cuscom. :更深层次的子组件名例子：.comyuchengcmiscuscuscom.agent（com.ucheng.cmis.cus.cuscom.agent） DAO表模型的DAO不做处理非表模型的JDBC实现的DAO规范如下：.comyuchengcmisbizcomponentnamesubbizcomponentname.dao注：bizcomponentname：业务组件名称。如：cussubbizcomponentname：子业务组件名称。如：cuscom. :更深层次的子组件名例子：.comyuchengcmiscuscuscomdao（com.ucheng.cmis.cus.cuscom.dao） INTERFACE. 图例含子组件包的情况：l COMn YUCHENGu CMISl bizcomponentname （组件名，详见缩写表如cus）n subbizcomponetname（子组件名如cuscom-对公客户）u componentu agentu daou domainn OPl INTERFACE(接口)无子组件包的情况：l COMn YUCHENGu CMISl bizcomponentname （组件名，详见缩写表如cus）n componentn agentn daon domainn OPl INTERFACE(接口)组件名英文缩写表英文缩写业务组件名备注PUB公共管理PUBlicCUS客户管理CUStomerFNC财务管理FiNanCeFNA财务分析FiNanceAnalysisPRJ合作方项目管理ProJectPRD产品管理ProDuctLMT额度管理LiMiTLMA额度测算LiMitAssessingACR授权管理ArcReditCTR合同管理ConTRactGRT押品管理GuaRanTyDOC档案管理DOCumentACC账务核算ACCountGRP集团管理GrpCCR客户评级ClientCreditRatingFCR债项评级FaCilityRatingLPC贷款定价LoanPriCingRSC风险分类RiSkClsesIQP贷前调查InQuiryPhaseCRP授信审批CreditPhasePVP签约放款ProVidePhasePSP贷后管理PoStPhaseARP资产保全AssetsRedeemingPhase 组件包内部按技术实现细分为operation、component两个包，EMP的operation放置在operation包中，组件类、组件代理类、组件配置文件放置在component包中 组件的接口、接口实现类均放置在组件接口包中，组件接口包与组件包平级放置，且命名规则为，对应组件名+后缀interface例如： 客户管理组件接口包名：com.yucheng.cmis.cusinterface2.1.3. 类/接口命名类名和接口名由英文字母和数字组成，首字不能为数字，不要出现下划线。英文采用大小写混合的方式，每个单词的首字母大写，整个名称首字母大写。名称应简洁并清晰地表达该类或接口的作用。对于继承EMP组件的类命名，应采用如下规则：对于Action、Service、Controller、View这样的可扩展组件，类名应以各自的组件类别作为后缀。如：CMISController等。operation: XxxOp.javaservice: XxxService.javaaction: XxxAction.javaextend: XxxExtend.java对于信贷业务系统中 对于继承CMISComponent的组件类，一律使用Component为后缀例如: CusComComponent 对于继承CMISAgent的组件代理类，一律使用Agent为后缀例如：CusComAgent对于继承CMISDao的技术实现类，一律使用Dao为后缀例如：CusComDao2.1.4. 成员变量及方法命名成员变量及方法名由英文字母和数字组成，首字不能为数字，不要出现“_”（对私有实例变量可以使用“_”前缀，但在其存取方法中则应将其前缀去掉）。英文采用大小写混合的方式，每个单词的首字母大写，但整个名称首字母小写。名称应简洁并清晰地表达该成员变量或方法的作用。常量则全部使用大写字母，并在单词之间使用下划线分割。对于JavaBean，作为属性的成员变量与其set、get、add方法原则上应保持名称对应，如param属性对应的set方法名为setParam。除了公开配置属性的set、get、add方法及一些必要的get方法外，Bean中尽量不要用set、get、add开头的方法执行其他操作，EMP应用开发中的方法尤其需要注意。2.1.5. 局部变量命名（及声明）局部变量命名规则和成员变量一致。为避免引用混淆，尽量不要使局部变量和成员变量重名，并在使用成员变量时统一采用this.变量名的形式。不要使用无意义的单字符变量名，但循环变量之类的临时变量可使用约定俗成的i、j、k等变量名。局部变量尽量在每个代码块（用大括号括起来的一段代码叫做代码块）起始的地方统一声明，而不是用到时再声明，但for循环的循环变量除外。2.2. 代码书写规范2.2.1. 总体原则每个Java源代码文件由一个单独的公共类或接口组成。当有私有的类或接口与公有的类或接口相关时，可以将它们放在一个文件中。代码的各个部分（各成员属性、方法定义等）之间应用空行来分隔。尽量避免超过2000行的文件。包声明及导入包声明之前不要有任何代码或注释。2.2.2. 类/接口定义类或接口定义各部分的出现顺序如下：1类或接口的JavaDoc2类或接口声明3类（静态）变量，按照public，protected，private的顺序4变量（属性等），按照public，protected，private的顺序6构造函数7方法，推荐按照功能实现方法、EMP Bean规定方法（toString等）、set/get方法这样的排列顺序2.2.3. 文本格式. 缩进为保证源代码清晰可读，要求必须进行缩进。采用4个空格作为缩进的单元，用TAB键进行缩进。. 换行每行应只出现一个语句，不要在一行中出现分号隔开的两个语句。变量的声明也尽量使每行只有一个声明。每行应小于80个字符，若某行代码过长，则按照如下原则换行。1.在逗号以后分行，注意换行后的缩进应与同级元素保持对齐（下同），如：var = someMethod1(longExpression1,someMethod2(longExpression2,longExpression3);2.在操作符之前分行，并兼顾运算优先级，如：longName1 = longName2 * (longName3 + longName4 - longName5)+ 4 * longname6; / PREFERlongName1 = longName2 * (longName3 + longName4- longName5) + 4 * longName6; / AVOID3.若用以上原则反而使代码更难读，则可根据实际情况调整换行及缩进，如：private static synchronized horkingLongMethodName(int anArg,Object anotherArg, String yetAnotherArg,Object andStillAnother) （若将下面两行与第一行的int对齐，则缩进太深导致右边距紧张）if (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) doSomethingAboutIt(); （若后面两个条件与第一行括号处对齐，则与下面的代码不好区分）. 代码块代码块起始的“”应置于类、方法、循环等声明语句的行尾，结束的“”单占一行，缩进匹配相应的开始语句。但若其中无内容时，“”应该紧跟着开大括号“”，写成“”的形式。大括号内部的代码缩进要比大括号深一层。当有else或多个else if连续时，将上一代码块的“”、else / else if 和“”写在同一行内。try-catch的格式也同样。若条件或循环语句的代码块只有一行，也应当明确使用大括号，避免之后添加语句时造成错误。. 异常处理所有try-catch捕获的异常不允许使用e.printStackTrace()，除明确知道可忽略的异常外，其他异常均需向上层抛出该异常。2.3. 注释规范所有代码中应存在详尽的程序注释和文档注释（JavaDoc）。程序注释描述代码的实现细节、疑难之处及待讨论问题，便于开发人员对代码进行理解和维护；JavaDoc则供没有源代码的开发人员参考，并让开发平台IDE可直接从代码中获取类相关信息。注释应随着代码的更新而更新，不应保留过期的注释。2.3.1. 程序注释程序中可以包含4种格式的注释：块注释、单行注释、跟踪注释、行尾注释，可根据需要选择使用。注释格式遵照标准的Java编程规范。程序注释应只出现在必要处，并尽量做到简洁明了。过多的注释反而会降低代码的可读性，同时也说明代码本身的质量需要改进。推荐用/ TODO标记来标出代码中尚未完成或需要完善的地方。2.3.2. 文档注释（JavaDoc）代码中的每个类、接口或成员都应有JavaDoc，放在各自的声明之前。缩进与各自的声明保持一致，注释的第一行（/*）不缩进，后继的每行文档注释都有一个空格的缩进（为了垂直对齐星号）。类和接口的成员包括构造器的文档注释中，第一行有4个空格的缩进，后继行则缩进5个空格。. 类/接口类或接口的JavaDoc应至少包含文字描述、作者、版本信息等必要标记。文字描述尽量以一个单行描述为起始，然后另起一段进行详细描述。为了使生成的HTML格式正确，文字描述中使用标签进行分段。JavaDoc中应当至少包含以下标记：author 作者since 该类最初出现于哪个版本（可附上日期）version 最新版本（可附上日期）. 成员变量/属性成员变量（属性）的JavaDoc应至少包含文字描述，格式与类或接口相同。若文字描述可以在一行内完成，则可使用/* 描述内容 */的单行格式。随着版本的演进，新增加的属性须附带版本和修改日期标记。. 方法方法的JavaDoc应至少包含文字描述，格式与类或接口相同。JavaDoc中应当至少包含以下标记：param 参数说明return 返回值类型和说明throws 抛出异常类型随着版本的演进，新增加的方法须附带版本和修改日期标记，若作者与类作者不同，还须指明该方法的作者。2.4. 内容规范2.4.1. toString各实现类应实现自己的toString方法，方便调试输出。格式可采用和组件配置文件相同的XML格式。2.4.2. Log代码中应在必要的地方输出日志，日志包含五个级别：DEBUG 调试信息，最详细的调试输出讯息，应包含足够的讯息，使得在没有源代码的情况下能够找出问题原因。TRACE 跟踪信息，比较详细的输出讯息，常用于跟踪该组件状态。INFO 一般信息，正常的输出讯息。WARNING 警告信息，当遇到不影响代码正常运行，但配置文件不规范或可能会造成问题的事件时记录。ERROR (FATAL) 出错信息，当遇到影响代码正常运行的错误或异常时记录。若该信息是由异常引起，则在日志中需要包含该异常。日志输出禁止使用System.out.println()以及System.err.println()。应统一使用EMPLog.log输出日志，并必须清楚当前输出的日志处于上述五个级别中的哪一个。2.4.3. 文件编码Java源代码一律采用UTF-8格式编码。2.5. JSP页面编码1. 为了规范页面处理，JSP页面开发中尽量使用标签，避免Java编码；2. 开发JSP页面尽量使用管理平台标签组件(cmisnew.tld)与EMP基础标签(emp.tld); 3. 对于管理平台标签与EMP基础标签无法实现的特定页面逻辑处理，尽量采用JSTL来实现；4. 在JSP页面禁止直接访问数据库表，禁止直接调用operation、action、service；5. jsp文件组织基本上跟包命名一样，一个包下面所有的jsp页面组织在同一个文件夹中，文件夹名称跟包的业务模块名称保持一致（包命名中com.yucheng.cmis.后面的部分，如果有二级目录，如acceptance.approval，则建相应的子文件夹acceptanceapproval），一个模块包下面的每一张表对应一个子文件夹，子文件夹名称为数据库物理表名。尽量保持表模型自动构造的jsp文件名不变，涉及到工作流的统一命名如下：详情表单页面：workflow.jsp发起申请列表：startWorkList.jsp待办审批列表：todoWorkList.jsp已办查询列表：doneWorkList.jsp办结查询列表：endWorkList.jsp列表页面根据业务需要可能并不需要完全的4个。其他1、一些简单的修改状态的操作，可以直接在页面中处理，不需要调用后台的operation，如修改合同状态：function doQianDing() var htbh = cmistaggroup_crd_cdxy.fields.crd_cdxy_htbh.getValue();var url=&crd_cdxy_htbh=+htbh+&crd_cdxy_htzt=200&selectColumns=htzt;window.location = url;2.6. 包结构定义2.7. 业务实体类（DOMAIN）编码1. 业务实体的VO，用于存储业务实体数据，贯穿EMP的OPERATION，业务组件的COMONET，AGENT，DAO层。2. DOMIAN为简单的JAVABEAN，若不包含复杂的属性（如包装类或其他的DOMAIN）只需定义对应的属性和get，set方法。3. 若含有复杂的属性或需要实现方法，则要在设计文档中体现。2.8. 操作类（Operation）编码1. Operation为业务逻辑实现的入口；2. 对于无需（或无法）直接在biz中使用组件组装的业务逻辑的入口代码，使用operation接口来实现；3. operation有明确的业务含意，是一次完整的业务原子交易过程；4. operation的命名为业务述语，而不是技术述语（例如，名为合同签定，而不叫修改合同状态）；5. 所有信贷系统的operation继承CMISOperation父类，而不直接继承Operation，以便与信贷系统进行统一的控制，如访问控制、事务控制等等；6. 在operation中可以自行进行数据库级事务操作，如获得、提交、回滚、关闭事务等，建议不自行处理数据库级事务；7. 在operation中对业务逻辑的实现过程尽量调用业务的Component，禁止直接在业务代码的operation中直接访问业务库表（不直接使用SQL），除简单的增、删、改、查外，其他复杂的数据库操作不能调用表模型的DAO，即不使用表模型敏捷开发的生成的OP直接操作数据库，只能通过COMPONENTS，调用AGENT，再由AGENT调用表模型或者通过JDBC实现的自有的DAO实现数据库操作。8. service从Context中取得（使用Context.getService方法）；9. 在operation中不可直接调用其它operation；2.9. 组件类（Component）编码1. Component为业务逻辑实现，是组件的实现类；2. Component必须继承CMISComponent；3. Component中实现业务逻辑中所有细节的业务处理，为上层Operation所使用；4. Component中可以直接访问业务库表，但建议使用组件对应的Agent来实现数据库操作；5. Component中不许进行数据库级事务操作，如提交、回滚；6. Com