Documenting Properties, Triggers & Annotations

同学们，咱们今天来聊聊怎么把Apex代码的“公共API”文档写清楚，这件事看起来基础，但对团队协作和长期维护特别重要。 咱们先想一下，一个类的公共API到底由什么构成？其实就是那些用 ，public， 或 ，global， 声明的属性、成员变量和方法。换句话说，只要外面的人能访问到的，都属于公共API。那在记录这些属性的时候，一定要讲清楚三件事：第一是它的，用途，，也就是这个属性到底是干什么的；第二是它的，数据类型，，比如是String、Integer还是自定义对象；第三是，使用说明，，比如有没有默认值、会不会自动改变、存取时有什么限制等等。举个例子，如果一个计数器变量 counter 是 public Integer，文档里就不能只写“计数器”，而要说明“记录当前已处理的记录数，会在每次调用后自增，请不要手动修改”。这样别人一看就心里有数了。 接下来要特别注意触发器。我们一直强调，不要直接在触发器里堆业务逻辑，那样既难测试也不容易复用。正确的做法是把逻辑委托给专门的，处理程序类，，也就是Handler类。那么写ApexDoc文档时，这个触发器上要记得加上一些标准的标记，尤其是 ，@since，，用来标明这个触发器是从哪个版本开始引入的，跟软件的迭代步调保持一致。 再往下，就是各种注解了。注解不仅是给编译器看的提示，更是给后面接手代码的人看的说明书，所以注释里必须把它们的含义和场景讲明白。 - ，@AuraEnabled，：这是让 Lightning 组件能调用这个方法。写注释时一定要说明是否启用了缓存，也就是 ，cacheable=true， 的设置，因为开启缓存后数据可能不实时，必须让调用方清楚这一点。 - ，@InvocableMethod，：这是给流（Flow）或过程构建器用的。