珊瑚虫~

2008-03-03

返回值、方法名称、参数、doc是影响接口清晰度的三大要素。
参数和返回值的结构往往是大家容易忽略的。
如果参数、返回值对象结构太过复杂，会对接口清晰度带来很大的影响。比如使用一个包含很多关系
的VO对象，接口的使用者设置的值与接口设计者期望的值无法通过明确的方式来约束，往往采用口头
的交流形成契约，接口的契约作用削弱了。
建议参数对象的层次不要太深，一层最好，不要包含其他的关系对象，关系对象提取到另外的参数中。
API的命名一定要从业务含义而非技术含义的角度出发，避免业务API的技术化倾向。
API的定义必须首先契合当前的界面设计，在此基础上做适当的冗余和超前，即是基于界面设计又高于当前的界面设计；避免闭门造车，脱离实际的API设计。
API的异常定义要仔细斟酌，不能千篇一律；避免过长的异常链，适当使用运行时异常，使用展现层异常处理GUARD机制统一处理。
API的注释要定义在接口而非实现中，要尽量详细，实现类中仅注释与实现相关的说明。