首页
/ FrankFramework项目中的Frank!Doc文档规范详解

FrankFramework项目中的Frank!Doc文档规范详解

2025-06-19 15:11:08作者:廉皓灿Ida

前言

FrankFramework作为一个企业级集成框架,其组件文档化是保证开发效率和质量的关键环节。Frank!Doc作为框架的官方文档系统,通过自动化方式从Java源代码生成结构化文档。本文将深入解析Frank!Doc的文档标注体系,帮助开发者掌握如何为框架组件编写规范的文档。

一、Frank!Doc核心标注体系

Frank!Doc提供了两种主要的文档标注方式:

  1. JavaDoc标签:以@ff为前缀的特殊标签
  2. Java注解:专门设计的文档注解

1.1 类级别文档控制

分组管理

  • @FrankDocGroup注解用于定义组件在文档中的分组位置
    • 接口上的注解:实现类会非独占性地加入该分组
    • 类上的注解:该类及其子类独占该分组

特殊标记

  • @ExcludeFromType:从特定类型文档中排除
  • @Label:为Java注解添加可视化标签

1.2 参数与属性文档

标注类型 作用域 功能说明
@ff.parameter 描述特定参数的用途
@Default 属性setter 指定属性默认值
@ReferTo 属性setter 引用其他类的文档描述
@Mandatory 属性/子元素 标记配置中的必填项
@Unsafe 属性/子元素 警告该属性不适合生产环境使用

1.3 继承与覆盖机制

  • {@inheritDoc}:继承父类或接口的文档
  • {@inheritClassDoc}:继承父类的类级别文档
  • @Reintroduce:调整配置项在文档中的显示顺序

二、高级文档特性

2.1 警示信息块

Frank!Doc支持四种级别的警示信息:

/**
 * {@ff.info} 一般提示信息
 * {@ff.tip} 使用技巧提示  
 * {@ff.warning} 需要注意的警告
 * {@ff.danger} 高风险警告
 */

2.2 兼容性处理

对于需要保持向后兼容的场景:

  • @Mandatory(ignoreInCompatibilityMode=true):在兼容模式下不作为必填项
  • @Protected:阻止属性或子元素被继承和显示

2.3 枚举值标注

使用@EnumLabel为枚举常量指定配置文件中使用的表示形式:

public enum LogLevel {
    @EnumLabel("error") ERROR,
    @EnumLabel("warning") WARN
}

三、属性文件规范

框架属性定义在AppConstants.properties中,遵循特定格式:

#### 分组名称

## 属性描述
## [Deprecated] 标记已废弃属性
property.name=defaultValue

## [Generated] 标记框架生成属性
generated.property

####

关键标记:

  • ! 开头的注释行
  • #### 定义属性分组边界
  • ## 多行属性描述
  • [Deprecated] 废弃警告
  • [Generated] 只读属性标记

四、最佳实践建议

  1. 文档完整性:所有公开API都应包含至少基础描述
  2. 版本控制:废弃属性必须标注[Deprecated]并说明替代方案
  3. 安全警示:对可能影响系统稳定性的属性使用@Unsafe
  4. 继承优化:合理使用文档继承减少重复内容
  5. 分组逻辑:按功能模块划分@FrankDocGroup分组

结语

Frank!Doc的标注体系为FrankFramework提供了强大的自文档化能力。通过规范使用这些标注,开发者可以:

  • 提高代码可维护性
  • 降低使用门槛
  • 保证文档与代码同步
  • 增强系统安全性提示

掌握这些文档规范,将显著提升您在FrankFramework项目中的开发效率和协作质量。

登录后查看全文
热门项目推荐