江西中磊支付科技有限公司 密级：内部中磊第三方支付平台软件开发规范文档编号：V1.0项目名称：江西中爰支付平台编 写：杨文辉编写日期：2014-4-16审 核：李骏审核日期：2014-6-13批 准：朱志龙批准日期：2014-6-17江西中磊支付科技有限公司2014年7月修订记录版本日期拟稿和 修改说明草稿2014-04-16拟稿VI. 02014-06-17正式签发文档江西中磊支付科技有限公司 网络设备操作于•册II内部1 引言 III1. 1 编写目的 III1.2 适用范围 III1.3 术语与简写 III1.4 参考文献 IV2 开发工具 V1. 开发工具要求 V3 注释 VI3. 1 基本原则 VI3.2 类注释 VI3.3 方法注释 VII3.4 其他注释 VIII3. 4. 1 常量注释 VIII3. 4. 2 分支注释 IX3. 4.3 调用注释 IX3. 4.4废弃方法注释 X3.4.5关键逻辑注释 XI3. 4.6问题注释 XI基常集方异贝 ・ ・ ・ ・原本量合法常I I V V V I I I I I I I X X XX X ・ ・ ・1. 1 继承与组合 XV1. 2 Str ing 与 Str in gBuffer XV1. 集合 XVI1. 对象 XVI1. 同步 XVII1. final XVIII6其他要求 XX2. 1 代码格式化 XX避免硬编码 XX日志规范 XXI资源释放 XXII中文信息处理 XXIII程序中 SQL XXV危险习惯 XXVI了解 Frame XXVI江西中磊支付科技有限公司 网络设备操作于•册1引言1.1编写目的编写本文档主要目的是：使江西中磊支付科技平台能以标准的、 规范的方式设计和编码。
通过建立编码规范，以使每个开发人员养成 良好的、统一的编码风格和习惯，提高程序的可靠性、可读性、可修 改性、可维护性和一致性，保证软件产品的质量1.2适用范围江西中磊支付平台相关人员1） 架构师2） 开发人员1.3术语与简写Log4jLog4j是Apache的一个开放源代码项目，通过使用Log4j,我们 可以控制日志信息输送的目的地是控制台、文件、GUI组件、甚至是 套接口服务器、NT的事件记录器、UNIXSyslog守护进程等；我们也 可以控制每一条日志的输出格式；通过定义每一条日志信息的级别， 我们能够更加细致地控制日志的生成过程最令人感兴趣的就是，这in 些可以通过一个配置文件来灵活地进行配置，而不需要修改应用的代 码1.4参考文献百度百科~Log4j；内部江西中磊支付科技有限公司 网络设备操作于•册2开发工具2.1开发工具要求编号软件工具备注1234567893注释3.1基本原则注释应该增加代码的可理解性注释要简洁注释信息不仅要包括代码的功能，还应给出原因除变量定义等较短语句的注释可用行尾注释外，其他注释当避 免使用行尾注释避免使用装饰性内容不要为注释而注释3.2类注释在类、接口定义之前对其进行注释，包括类、接口的目的、作用、 功能、实现的核心算法、示例程序等。
例如：/***类描述：
* YYYYYY支付平台业务常用方法工具类*@author chenjda@修改记录：1. chenjda 2010-12-23 添加 maptoResponse 方法，将 map 转为Response方法〈br>**/public class CardUtil {• • •}注:作者、修改人使用itcode3.3方法注释依据标准JavaDoc规范对方法进行注释，明确方法功能、作用、 各参数含义以及返回值参数注释需注明其中文含义、取值范围等返回值注释需注明方法正常执行后的返回情况异常注释需注明什么情况、什么时候、什么条件下会引发什么样 的异常例如：/***方法描述：
YYYYYY支付平台实现*@aulhor liulm@param cardSeqXo XX 序列号@param logoutReason 注销原因@param logoutTime 注销时间©param businessNo 业务流水号@param certNo 凭证号@throws Exception*/public void cancelCard(String cardSeqNo, String1ogoutReason,Timestamp logoutTime, String businessNo, StringcertNo）throws Exception {• • •}方法的传入参数为对象的处理方式：如果该对象是java的集合类，例如：List、Map、Set,需要 详细说明支持前端传入哪些参数（所有的参数，见6.7）o如果该对象是一个业务bean （比如（）对象），如果该对象的所 有信息都被使用，可不必详细说明对象的各个信息项，但本方 法需要特殊处理的信息需注释。
如果方法只使用该对象的某些 信息，需明确指出该对象的哪些信息会被本方法使用（这种方 法一般来说可优化为操作具体的信息项或使用java的集合类 的方法）3.4其他注释3.4.1常量注释应对重要的常量加以注释，以说明其含义public的常量使用 JavaDoc注释、private的常量使用//注释例如：例1, private的常量• • •//默认运算精度private static final int DEF_SCALE = 2；例2, public的常量/***库存位置为XX*/public final static String STORE_POS_TELLER = ”3”；• • •3.4.2分支注释应对不易理解的分支条件表达式加注释，以说明其逻辑控制例如：• • •if (ChargeCommon. isChargeTxn(txn_tp)) { // 当前交易是充值 申请• • •}else{ //江西中磊支付平台• • •}• • •3.4.3调用注释调用其他类的方法时需要有调用注释例如：• • •//江西中磊支付平台cardManager・ logoutOldSlandardCard(CardConstants. CARD_PR 0CESS_C0DE504, CardConstants. CARD_PR0CESS_NAME504,business^no, o1d_card_seq_no, branchno, branchname, tellerno, tellername, operTime, xdo)；IX内部江西中磊支付科技有限公司 网络设备操作于•册调用本类的业务方法时需要有调用注释。
例如：• • •//获得查询数据的sqlString sql = getChangeAsignSql(paperType, paperNo, citizenCardNo, null)；• • •3.4.4废弃方法注释由于某种原因需要废弃的对外公共方法，需使用©deprecated标记例如：/***方法描述：
*江西中磊支付平台实现*@author liulm@param cardSeqXo XX 序列号@param logoutReason 注销原因©param logoutTime 注销时间@p8min businessNo 业务流水号@param cert No 凭证号@throws Exception©deprecated江西中磊支付平台需返回操作表的主键信息， 已被返回map的同名方法替代/©Deprecatedpublic void cancelCard(String cardSeqNo, String logoutReason,Timestamp logoutTime, String businessNo, String certNo)x内部江西中磊支付科技有限公司 网络设备操作于•册throws Exception {• • •}3.4.5关键逻辑注释代码中使用的复杂算法、重要的核心逻辑部分需要有注释，说明算法逻辑。
例如：• • •//以下代码使用迭代算法，递进计算整个机构的收入• • •迭代计算代码• • •3.4.6问题注释对系统实现不够优化（当时使用了不完善的代码）的代码，或是 后续需要调整的代码需使用TODO标记，如下：• • •// TODO如果有方法知道IDENTITY_ARR下面ITEM节点的数量就 可以去掉catch• • •Eclipse可以提醒仍需执行的任务在代码中添加T0D0注释来提 醒开发人员还有特定的任务要完成，或者特定的情况要处理o Eclipse 利用它对Java结构的知识找到任何以TODO开头的注释，并将它添加 到一个特殊的 Tasks 视图（打开 Window Menu > Show View > Other > Basic > Tasks就可看到）这样，Eclipse可以提供一个全面的待完 成的任务列表15内部4命名规范的命名能使程序更易阅读、更易理解、更易维护4.1基本原则使用可以准确说明变量/字段/类/接口/包等的完整的英文描 述符例如，采用类似 cardSeqNo , sendNotice或 Month2YearManager这样的名字，严禁使用汉语拼音及不相关 单词命名。
釆用大小写混合，提高可读性一般情况下都是使用小写字母, 但是类、接口名的首字母、任何中间单词的首字母、全局变量 大写尽量少用缩写，但如果一定要使用，应当使用公共缩写和习惯 缩写，如实现(implement)可缩写成impl,严禁滥用缩写避免使用长名字(最好不超过25个字母)避免使用数字4.2常量采用完整的英文大写单词，在词与词之间用下划线连接，例如： CARD_SHELL_N()NE (卡壳-未提供)4.3集合一个集合，例如数组和矢量，应采用复数命名来表示队列中存放 的对象类型命名应采用完整的英文描述符，名字中所有非开头的单 词的第一个字母应大写例如：Vector cards 二 new Vector () ； // 卡向量Array apps = new Array () ； // 应用列表4.4方法方法的命名应采用完整的英文描述符，大小写混合使用，所有中 间单词的第一个字母大写方法名称的第一个单词常常采用动词取值类方法使用get前缀，设值类方法使用set前缀，判断类使 用 is (has)前缀例如:getCardlnfo()se LCardDaLaPreparat i on()islnStock()基于江西中磊支付平台VI. 0特殊的控制需要，一个需要spring 事务控制的方法,必须以do开头。
例如:doSaveChange4.5异常异常类名由表示该异常类型的单词和Exception组成，如 CtaisServiceExceptiono异常实例一般使用e、ex等，在多个异常 时使用该异常名或简写加E, Ex等组成，例如：SQLEx5性能系统性能的提升并不是一蹴而就的，而是由所有的开发者良好的 编程习惯、合理的编程技术积累得到的5.1继承与组合尽量使用组合来代替继承，可以使类的层次不至于过深，使类与 类、包与包之间的耦合度更小，系统更具可扩展性5.2 String 与 StringBuffer不要使用如下String初始化方法：String personName = new String （ “江西中磊支付平台”）；这将产生两个对象，应当直接赋值：String personName = “江西中磊支付平台”；在处理变长字符串的时候要尽量使用StringBuffer类， StringBuffer 类是构成 String 类的基础oString 类将 StringBuffer 类封装了起来，为开发人员提供了一个安全的接口（以花费更多时间 为代价）当我们在构造字符串的时候，用StringBuffer,构造完成 后将StringBuffer对象转换为String对象。
比如：如果有一个字符 串必须不断地在其后添加许多字符来完成构造，那么我们使用 StringBuffer对象和它的append（）方法如果我们用String对象 代替StringBuffer对象的话，将会花费许多不必要的创建和释放对 象的CPU时间和存储空间5.3集合避免使用Vector和HashTable等旧的集合实现，这些实现的存在 仅是为了与旧的系统兼容，而且由于这些实现是同步的，故而在大量 操作时会带来不必要的性能损失在新的系统设计中不应当出现这些 实现,使用 ArrayList 代替 Vector,使用 HashMap 代替 HashTable若确实需要使用同步集合类，可使用如下方式获得同步集合实例:Map map = Collections, synchronizedMap(new HashMap())；由于数组、ArrayList与Vector之间的性能差异巨大(具体参见 《Java fitbalD),故在能使用数组时不要使用ArrayList,尽量避 免使用Vector05.4对象尽量避免在循环中频繁构建和释放对象如无必要，不要序列化 对象例如：• • •for (int i=0； KstorageDetailRCount ； i++) {O_cd_storage_detai 1 oStorageDetail =(O„cd_storage_detai1)dwStorageDetai1・ getRow(i)；insertOrUpdateStockDetai1(dwStockDetai1,T, oStorageDetail,oStorageReg,stockSumld)；}江西中磊支付科技有限公司 网络设备操作于•册分析下这段代码，这段代码在computStockln (计算入库及接受) 方法中，是根据dwStorageDeta订中的数据插入或更新库存明细数 据 o 但 " O_cd_storage_detai1 oStorageDeta订 = (O_cd_storage_detail)dwStorageDetail. getRow(i)； ” 这段代码是 可以避免频繁构建对象的，因oStorageDetail在 insertOrUpdateStockDetai 1中只是传递信息使用，上传代码可优化 为以下代码：• • •()_cd_storage_detai1 oStorageDetail 二 null；for (int i=0； KstorageDetailRCount； i++) {oStorageDetail 二(0_cd_storage_detai1)dwStorageDetaiL getRow(i)；insertOrUpdateStockDetai1(dwStockDetai1,-1, oStorageDetail,oStorageReg,stockSumld)；}• • •5.5同步在不需要同步操作时避免使用同步操作类，如能使用ArrayList 时不要使用Vector0避免使用synchronized关键字。
如必需同步， 则尽量将同步影响最小化，即将同步作用到最需要的地方，避免大块 的同步块或方法等例如：江西中磊支付平台的单笔申请是使用半成品卡来制一张新的标准卡，而补卡、换卡同样是使用半成品卡来生成一张新的标准卡，多个业务使用同一个资源，如何保证半成品卡的使用是同步的，现在的处XVII 内部江西中磊支付科技有限公司 网络设备操作于•册理方式是在单笔申请、补卡、换卡的核心逻辑中增加同步变量，保证 对江西中磊支付平台的使用是同步的• • •Synchronized (ConimonCardParam. SYNCHRO_STR) {• • •//江西中磊支付平台使用逻辑• • •}• • •CommonCardParam 类中定义同步字符串 SYNCHR()_STR：/***单笔申请、补换同步对象*/public final static String SYNCHRO_STR = "synchronized'1 ； 注：需要使用同步的地方请与技术负责人沟通确认，因同步在集 群环境需要有特殊的解决方案5.6 final将参数、方法、类声明成final可提高程序响应效率，故此：不需要重新赋值的变量(包括类变量、实例变量、局部变量) 声明成final o所有方法参数声明成finale若方法确定不会被重载，则声明成finalo私有(private)方法不需要声明成finalo若类确定不会被继承，则声明成finalo26内部6其他要求6.1代码格式化所有的代码必须格式化，在单个文件中，使用ctrl+shift+f （打 开文件，右键点击文件内容，选择Source>Format）可以格式化一个 文件。
Eclipse 统一使用 Eclipse [built-in]模板，位置： Window->Preferences->Javo->Code Style->Formatter, 点击 New 按 钮，New Profile 的Profile name 录入为"VI. 0,?, Initialize settings with the follow profile 选择"Eclipse [built-in]”，选定 Open the edit dialog now的复选框，点击OK按钮，选择tab页Line Wrapping,在左上角的 Maximum line width 改为 ”120”，点击 OK 按 钮，返回 Formatter 页，Active profile 选择” VI. 0"（默认是” VI. 0”），点击0K按钮6.2避免硬编码在程序里出现硬编码（比如应用标识80）会降低程序的可读性、可 维护性和可扩展性，故规定不得出现硬编码避免的方法是把硬编码 定义为一个常量注意这个常量的命名应该能表达该数的意义，并且 应该全部大写，以与对应于变量的标识符区别开来常量分两种，一种是只在当前功能中使用，对于整个系统没有意义的，可将该常量放在当前功能的类级别。
另一种是系统级别的常量, 需将该常量放在系统常量类中，便于监控及统一调整6.3日志规范江西中磊支付平台使用Log4j进行日志操作以下规定如何使用Log4jo异常块中如何输出日志首先实例化一个日志类，例如：protected final Log log = LogFactory. getLog(getClassO)；发生异常时输出日志(一般在接口服务层)，例如：try {• • •}catch(Exception ex) {log. error ( “单笔申请提交服务异常” ,ex)；this. setResponse(0, 2000, CardUtil.getReturnMap (w 0 ”+CardUtil. getChineselnfo(infoConstants. CHAXGE_SAVE_ERROR)； + ,,,,));}关键逻辑前后输出日志关键逻辑前后输出日志使用info级别的输出API关键逻辑 是指重要的、影响大的核心代码以充值举例，充值是否正常完 成，充值接收的申请报文，充值结束的返回报文，对于正常的系统运行是有记录的价值的。
• • •log. info( “充值开始，请求报文："+ xdo. toXML())；• • •//充值操作• • •log. info( “充值结束，返回报文："+ response. toStringO):• • •调试信息输出调试信息使用debug级别的输出API• • •if (log. isDebugErmbled()){log. debug( “测试信息…”)；}• • •6.4资源释放finally：异常处理时用来执行清除操作，通常是关闭文件或者释 放内存无论有没有抛出异常，如果有finally块，最终都会被执行 文件资源释放是典型的需要资源释放的场景，例如：• • •File file = new File('7home/admin/a. txt")；FileOutputStream out = null；try {out = new FileOutputStream(file)；file. deleteO ；while (true) {try {Thread. sleep(lOOO)；} catch (InterruptedException e) {e.printStackTrace()；}}} catch (IOException e) {e.printStackTrace()；} finally {try {if(out!=null) {out. close ()；}} catch (IOException e) {e.prinLStackTrace()；}}• • •6.5中文信息处理新增info, properties配置文件，配置''检索主键”对应的中文 信息。
当在代码中需要使用中文信息时，使用“检索主键”来查找对 应的中文信息，这样使得系统的中文信息可配置，可更好地支持中文 调整及二次开发例如：在后台程序中想要返回前端的中文提示信息“采集库存在，社保 存在，卫生存在”,定义该信息的检索主键为acim_queryPerson 使用 MyEclipse 打开 info, properties 文件，点击"Properties” tab 页，点击 Add 按钮，Name 填"cim—queryPerson”，Value 填"采集库 存在，社保存在，卫生存在”，点击“Finish”按钮修改CardUtil类，支持获取info, properties的中文信息:• • •//增加以下代码private static PropertyManager infoProManager 二PropertyManager・getPropertyManager( “info” )；• • •//增加以下代码public static String getChineseInfo(String properLyName) {String result 二 null；result = infoProManager・getProperty (propertyName)； return result；}• • •修改中文信息“检索主键”类infoConstants,增加“检索主键” 的映射。
• • •/***江西中磊支付平台查询提示主键*/public final static String CIQUERYPERSON =CardUti 1・ getChineselnfo(,rcim_queryPersorT)；在java中如何获取cim_queryPerson的中文信息:String queryinfo 二 infoConstants. CIQUERYPERSON:• • •6.6程序中SQL尽量避免直接使用SQLo在必须使用SQL时（比如多表关联查询）,SQL字符串拼接使用StringBugffer, SQL语句使用小写语法例如:final StringBuffer selectSB 二 new StringBuffer(120)； selectSBappend("select ”).append(COLSQUERY)append(" f rom cd_card_prepare a where a・ card_seq_no=r ”)append(cardSeqNo)；appendL union all select ”)；.append(COLSQUERY)；append(" from cd_cardp_preprule a wherea. cardp_code=，”)；append(cardpCode)；append ('\'')；final DataWindow selectDW =DataWindow・ dynamicCreate(selectSB.toStringO)；6.7危险习惯注意你的代码不要使用System, out. print System, exit > printStackTrace 等方法。
6,8 了 解 Frame每一个开发人员需要学习sm@rtFrameFusion开发指南.doc,虽然 这个指南跟我们现在有些不一样，但Frame基础思想及技术能使你对 自己的工作有更好的认识。