运算逻辑命名规范及编写规范

【适用范围】

通用


【内容】
近期在整理构件库的过程中，同时整理了一些构件开发的规范，以下是整理的运算逻辑命名规范及开发规范，供大家参考

运算逻辑命名规范：
1、 运算逻辑类路径规划：com.primeton.eos.bizlets.package名.运算逻辑类名，例如：com.primeton.eos.bizlets.database.Database,其中database为package名，表示下面包含数据库操作相关的运算逻辑类，Database是其中一个具体的运算逻辑类，集中了基本的数据库操作的运算逻辑，在对应package下还可以包含其他的运算逻辑类，例如com.primeton.eos.bizlets.database.DatabaseExt
2、 运算逻辑类名建议首字母大写，由多个单词构成时，每个单词首字母大写，每个运算逻辑类包含一组具有某些共同特性的运算逻辑，禁止在运算逻辑杂乱无章分布在不同的运算逻辑类中。正确的示例如下：
a) com.primeton.eos.bizlets.database.Database ：包含基本数据库操作运算逻辑
b) com.primeton.eos.bizlets.database.DatabaseExt ：包含扩展数据库操作运算逻辑
3、 运算逻辑名称＝“BL_”＋动作＋所操作的对象，其中动作单词首字母小写。为保持运算逻辑名称的精简，允许动作和所操作对象名称使用可理解的缩写形式。以下常见的运算逻辑：BL_getRandomNumber、BL_padStringLeft、BL_insertEntity等
4、 运算逻辑以“BL_”开头，以下格式均不符合规范：“bl_”、“Bl_”、“BL-”
5、 某些运算逻辑支持参数可以按组增加，则建议运算逻辑名后加“Batch”，如BL_setNodevalueBatch

运算逻辑编写规范：
1、 运算逻辑取参数原则上按参数序号获取，即使用BizContext 类的getParaObjectAt(0)函数，不建议按参数名称取参数，即BizContext 类的getParaByName(参数项名称)，
2、 运算逻辑原则上建议不抛出异常，而是通过捕捉异常后设置返回值返回，异常信息可以通过日志接口记录到日志文件中。如果抛出异常，要求能在构件对应的文档中明示抛出哪些异常。
3、 在运算逻辑中如果存在多处错误返回，应根据不同错误返回不同返回值（如-1、-2、-3……），这样有助于进行错误定位
4、 运算逻辑中有关调试、出错提示等，一律使用EOS平台发布的日志记录接口TPLogger. log(Object caller,int level,String strMsgKey,String strMsg,LogContext context)，详细用法参见构件参考手册API 接口部分
5、 运算逻辑中需要进行XML的相关处理时，使用EOS平台发布的XML处理接口类BNXMLUtil，详细接口参见构件参考手册API 接口部分
6、 运算逻辑获取参数时，强制转换的类型为String或Element（Node），对于其他int、float、double类型可以通过String类型转换获得
7、 一般情况下，运算逻辑正常返回值为1；返回负值表示捕捉到异常或因数据不合要求导致处理中断，需要进行分支处理；返回0或其他正数表示处理完成，但可能存在某些警告信息，例如用BL_expandEntity查询指定条件的某条记录时，可能符合查询条件的记录有多行，则返回第一行记录，而返回值为记录行数。
8、 运算逻辑参数项设置原则：
a) 原则一：一般将第一个参数设置为输出，即运算逻辑执行中对数据进行处理后通过第一个参数项返回，例如，查询多行记录的运算逻辑BL_queryEntityAll，第一个参数为查询结果输出的节点，第二个为查询条件输入的节点。其他如BL_getLength、BL_joinStrings等
b) 原则二：对于重要性较低的参数项建议作为最后一个参数项，同时允许不设置时取最常用的值作为缺省值，例如BL_getLength的第三个参数为计算字符串长度的方式，等于1时表示计算字节长度，其他值则计算字符串长度，则可以不设置该参数项，通过在运算逻辑中进行判断，如果存在该参数项，则取参数项的值进行判断，如果不存在，则取缺省值（计算字符串长度）。
c) 原则三：不建议运算逻辑设置太多参数项（对于支持批处理的除外），如果参数项超过5个，建议充分利用XML的可扩展特性，通过Entity的节点方式处理，例如发送邮件的运算逻辑BL_sendMail，将整个邮件信息（如发件人、收件人、抄送人、主题、内容、附件等等）放入一个EOSEntity中以一个参数传入，而不是每项作为一个参数传入，在运算逻辑中通过取Entity节点的子节点获得各项参数。注意，这种方式必须严格约定Entity下各个Field的节点名称。

典型运算逻辑类的截图：

【备注】