ThinkR-open/fusen 项目使用技巧与最佳实践指南

前言

ThinkR-open/fusen 是一个创新的R包开发工具，它通过扁平化开发模式（flat development）彻底改变了传统R包开发流程。本文将深入介绍fusen的各种实用技巧，帮助开发者更高效地利用这一工具进行R包开发。

一、命名规范与快捷方式

1.1 代码块命名灵活性

fusen允许开发者使用简化的代码块命名方式，提高开发效率：

• 函数代码块：可以使用fun-、fun_或fun-自定义名称格式
• 示例代码块：支持ex-、ex_或ex-自定义名称格式
• 测试代码块：可采用test-或test-自定义名称格式
• 开发代码块：允许dev-、dev_或dev-自定义名称格式

1.2 模板快捷创建

为提升开发效率，fusen提供了多个快捷函数：

• add_additional()：快速添加额外模板
• add_full()：创建完整功能模板
• add_minimal()：生成最小化模板

二、扁平模板的编织与开发

2.1 开发环境配置

虽然扁平模板可以像普通Rmd文件一样编织运行，但需注意以下几点：

1. 在模板开头使用development代码块声明所需包：

library(glue)
library(stringi)

2. 注意示例和测试代码需要独立运行，确保完整性

3. 包含inflate()调用的开发代码块应设置eval=FALSE避免副作用

2.2 文档与示例控制

对于不希望运行的示例代码：

1. 使用eval=FALSE参数阻止在vignette中运行
2. 结合#' \dontrun{}语法控制函数示例运行

# 在vignette中不运行但在函数示例中运行
myfunction(10)

# 在两者中都不运行
#' \dontrun{
myfunction(12)
#' }

三、数据与文件管理技巧

3.1 数据集文档化

在function代码块中直接文档化数据集：

#' cars数据集
#'
#' 来自'datasets'的标准数据.
#'
#' @format 包含50行2列的数据框:
#' \describe{
#'   \item{speed}{数值型}
#'   \item{dist}{数值型}
#' }
#' @source Ezekiel, M. (1930) Methods of Correlation Analysis. Wiley.
"cars"

3.2 测试数据读取

处理测试数据路径的双重适配：

the_file <- "my_file.csv"
if (!file.exists(the_file)) {
  the_file <- file.path("tests", "testthat", the_file)
  if (!file.exists(the_file)) {
    stop(the_file, "不存在")
  }
}
my_file <- read.csv(the_file)

四、高级开发技巧

4.1 多函数管理

在单个R文件中组织多个函数的几种方法：

1. 标题结构法：在同一标题下组织多组代码块
2. @rdname标记法：使用相同rdname标记函数
3. @filename标记法：fusen专用标记实现文件合并
4. 代码块参数法：设置filename参数统一文件名

4.2 批量函数预填充

在现有模板中添加多个函数结构：

# 定义函数名列表
fun_nms <- c("func1", "func2", "func3")

# 生成代码块内容
l_chunks <- purrr::map_chr(fun_nms, fusen:::build_fusen_chunks)
chunks <- paste(l_chunks, collapse = "")

# 替换模板中的占位符
flat_rmd <- sub("^HERE$", chunks, readLines(path_flat_rmd))

五、工作流优化

5.1 开发时函数加载

无需inflate即可加载当前扁平文件中的函数：

fusen::load_flat_functions()  # 加载当前文件
fusen::load_flat_functions(flat_file = "dev/flat_full.Rmd")  # 加载指定文件

5.2 批量膨胀操作

使用inflate_all()一次性处理多个扁平文件，显著提升开发效率。

5.3 与golem框架集成

将fusen与golem结合使用，实现业务逻辑与UI的清晰分离：

1. 先创建golem项目
2. 添加扁平文件
3. 创建对应模块保持一致性

golem::create_golem('my.app')
fusen::add_minimal_flat(flat_name = "module1")
golem::add_module(name = "module1")

六、特殊场景处理

6.1 自定义vignette信息

控制vignette标题与索引条目：

inflate(vignette_name = c("显示标题" = "01-索引条目"))

6.2 禁用vignette生成

仅构建内部函数时取消vignette：

inflate(vignette_name = NA)

6.3 Quarto文件支持

fusen兼容.qmd格式的扁平文件，虽然最终生成的vignette仍为Rmd格式，但开发过程可使用Quarto特性。

结语

通过掌握这些技巧，开发者可以充分发挥fusen在R包开发中的潜力，实现更高效、更规范的开发流程。无论是单个函数的小型包，还是包含多个模块的复杂应用，fusen都能提供灵活而强大的支持。