NC接口设计规范.doc

NC接口设计规范v1.0
本文档适合于NC5.0及以后版本。
一、 名词描述：
a) 接口设计：指将本业务需要给其他业务提供的服务方法和进行远程调用的方法提取为接口的设计方式；
b) 接口：指上述设计所涉及的类，包括接口类及接口方法中所使用的业务对象（如VO）和业务异常。不包括接口类的具体实现类；
c) 代码设计：指代码即为设计文档，要求其注释可生成JavaDoc文件；
d) 设计阶段：分为总体设计、详细设计；
二、 设计要求：
a) 设计工具：采用Eclipse直接进行代码设计；
b) 文档格式：JavaDoc文档，文档中包含接口中使用的接口类、业务对象和业务异常的描述；
c) JavaDoc注释要求：
符合标准JavaDoc文档所要求的输写规范，具体写发详见JDK DOC帮助文件。对具体对象要求如下：
i. 接口类：
1. 类注释：类注释应该在import语句的后面在类声明的前面；
/**
* （接口类简要描绘，必须以句号为结束）.
* <p>
* <strong>提供者：</strong>（提供业务组）
* <p>
* <strong>使用者：</strong>（使用业务组，若分方法描述可省略此项）
* <p>
* <strong>设计状态：</strong>（指出接口类设计阶段：总体、详细）
* <p>
* @version（接口版本）
* @author （接口类总设计负责人）
*/
2. 方法注释：方法注释要紧靠方法的前面；
/**
* （接口方法简要描述，必须以句号为结束）.
* <p>
* <strong>调用模块：</strong>
* （明确指出本接口适用范围：公共、私有或具体应用业务模块）
* <p>
* <strong>最后修改人：</strong>
* <p>
* <strong>最后修改日前：</strong>
* <p>
* <strong>用例描述：</strong>
* <p>
* @param （参数用途描述）
* @return （返回值描述）
* @throws （异常描述）
* @since （开始使用的NC版本）
* @see （关联类）
*/
ii. 业务对象类：
1. 类注释
/**
* （业务对象类简要描绘，必须以句号为结束）.
* <p>
* <strong>拥有者：</strong>（拥有业务对象的业务组）
* <p>
* <strong>设计状态：</strong>（指出接口类设计阶段：总体、详细）
* <p>
* @version （业务对象版本）
* @author （作者/最后修改人）
* @since （开始使用的NC版本）
*/
2. get方法注释
/**
* （属性简要描述，必须以句号为结束）.
* @return
*/
3. set方法注释
/**
* （属性简要描述，必须以句号为结束）.
* @param （参数用途描述）
*/
iii. 业务异常类：
1. 类注释
/**
* （业务异常类简要描绘，必须以句号为结束）.
* <p>
* <strong>拥有者：</strong>（拥有异常的业务组）
* <p>
* <strong>设计状态：</strong>（指出接口类设计阶段：总体、详细）
* <p>
* @version（业务异常类版本）
* @author （作者/最后修改人）
* @since （开始使用的NC版本）
* @see （关联类）
*/
2. 构造方法注释
/**
* （异常构造的简要描述，必须以句号为结束）.
*/
d) 不同设计阶段要求：
i. 总体设计：明确描述接口类名称和用途，接口方法名称和用途；
ii. 详细设计：明确描述接口方法参数和返回值，明确描述方法使用的业务对象和异常，明确描述接口方法用例；
三、 应用实例
a) 接口类：nc.itf.uap.test.ITestBService
b) 业务对象类：nc.vo.uap.test.BusinessVO
c) 业务异常类：nc.bs.uap.test.BusinessException
d) 生成的JavaDoc文件