moai-lang-r

快速参考（30 秒）

R 4.4+ 开发专家——tidyverse、ggplot2、Shiny、renv 和现代 R 编程模式。

自动触发：扩展名为 .R 的文件、.Rmd、.qmd、DESCRIPTION、renv.lock，以及 Shiny 或 ggplot2 相关讨论

核心能力：

• R 4.4 特性：原生管道运算符、反斜杠 Lambda 语法、改进的错误消息
• 数据处理：dplyr、tidyr、purrr、stringr、forcats
• 可视化：ggplot2、plotly、scales、patchwork
• Web 应用：Shiny、响应式、模块、bslib
• 测试：testthat 3.0、快照测试、模拟
• 包管理：renv、pak、DESCRIPTION
• 可复现报告：R Markdown、Quarto
• 数据库：DBI、dbplyr、pool

快速模式

dplyr 数据管道模式：

加载 tidyverse 库。通过管道处理数据：使用 filter 筛选年份为 2020 或之后的数据；使用 mutate 添加 revenue_k（revenue 除以 1000）和 growth（当前 revenue 减去滞后 revenue，再除以滞后 revenue）；使用 group_by 按 category 分组；然后使用 summarise 汇总，计算 total_revenue（总和）、avg_growth（平均值，na.rm 设为 TRUE），并将 groups 设为 drop。

ggplot2 可视化模式：

加载 ggplot2 库。使用数据和 aes 映射创建 ggplot，将 x 映射到 date、y 映射到 value，并将 color 映射到 category。添加 linewidth 为 1 的 geom_line 和 size 为 2 的 geom_point。使用 scale_color_viridis_d 设置颜色刻度。使用 labs 添加标题、坐标轴标签和颜色图例。使用 theme_minimal 设置简洁外观。

Shiny 基础应用模式：

加载 shiny 库。使用 fluidPage 创建 ui，其中包含用于从 mtcars 列名中选择变量的 selectInput，以及用于绘图的 plotOutput。创建 server 函数，参数为 input、output 和 session。在 server 中，将 renderPlot 赋给 output 中的 plot，使用 mtcars 和 aes 创建 ggplot，并在直方图中通过 .data 代词使用 input 中的变量。通过将 ui 和 server 传入 shinyApp 来创建应用。

---

实现指南（5 分钟）

R 4.4 现代特性

原生管道运算符：

通过管道处理数据：使用 filter 删除 NA 值；使用 mutate 添加 log_value（value 的对数）；使用 summarise 计算 mean_log。对于非首个参数位置，在 lm 公式调用中使用下划线占位符，并传入 data 参数。

反斜杠 Lambda 语法：

使用 map 搭配数据和反斜杠 x 语法，计算 x 的平方。使用 map2 搭配两个列表和反斜杠 x y 语法，计算 x 加 y。在 dplyr 上下文中，使用 mutate 和 across 选择数值列，并应用反斜杠 x 语法调用 scale 函数，再提取第一列。

tidyverse 数据处理

dplyr 核心动词：

加载 dplyr 库。通过管道处理 raw_data：使用 filter 筛选 status 为 active 且 amount 为正的数据；使用 select 选择指定列；使用 mutate 添加 month（通过 floor_date 计算）和 amount_scaled（amount 除以最大值）；然后按 date 降序排列。对于分组汇总，通过管道使用 group_by 分组，再用 summarise 计算 n（计数）、sum 和 mean，并将 groups 设为 drop。

tidyr 重塑模式：

加载 tidyr 库。要将宽格式转换为长格式，使用 pivot_longer，并将 cols 设为以 year 前缀开头的列、names_to 设为列名、names_prefix 设为要移除的前缀、values_to 设为值。要将长格式转换为宽格式，使用 pivot_wider，并设置 names_from 和 values_from，同时添加 values_fill 处理缺失值。

purrr 函数式编程：

加载 purrr 库。使用 map 遍历 files，并通过 Lambda 读取每个文件的 CSV。使用 map_dfr 按行合并，并通过 id 参数设置来源列。使用 map_dbl 提取数值结果，计算 mean 并将 na.rm 设为 TRUE。要处理错误，使用 safely 包装 read_csv，创建 safe_read。使用 safe_read 映射 files，提取结果，并使用 compact 筛选成功项。

ggplot2 可视化模式

完整绘图结构：

加载 ggplot2 和 scales 库。使用 ggplot 创建 p，指定数据以及 x、y 和按组着色的美学映射。添加带有 alpha 和 size 的 geom_point，以及 method 为 lm 且显示标准误的 geom_smooth。应用带逗号标签的 scale_x_continuous、带美元标签的 scale_y_log10，以及使用 Set2 调色板的 scale_color_brewer。按 category 添加 facet_wrap，并设置 free_y 刻度。使用 labs 添加标题、副标题和坐标轴标签。应用带有 base_size 的 theme_minimal，并通过 theme 设置图例位置。使用 ggsave 保存，指定文件名、绘图对象、尺寸和 dpi。

使用 patchwork 绘制多个图：

加载 patchwork 库。创建 p1（直方图）、p2（散点图）和 p3（箱线图）。使用管道和括号组合布局，使 p1 位于 p2 旁边，且二者位于 p3 上方。添加 plot_annotation，设置标题和 tag_levels。

Shiny 应用模式

模块化 Shiny 应用：

创建一个接受 id 参数的 dataFilterUI 函数。使用 NS 函数创建命名空间。返回一个 tagList，其中包含初始选项为 NULL 的 category 选择输入，以及 range 滑块输入。创建一个接受 id 和 data 响应式对象的 dataFilterServer 函数。使用 moduleServer 和内部函数。在 observe 块中，提取唯一类别并更新 selectInput。返回一个响应式对象，根据 category 和 range 输入筛选数据，并使用 req 验证输入。

响应式模式：

在 server 函数中，创建 processed_data 作为响应式对象，按输入 year 筛选数据并缓存结果。创建初始值为 0 的 counter 响应式值。对输入 increment 使用 observeEvent 更新 counter。对输入 run_analysis 使用 eventReactive 执行开销较大的计算。对搜索输入的响应式对象应用 300 毫秒的 debounce，以处理快速输入。

testthat 测试框架

测试结构模式：

加载 testthat 库。为 calculate_growth 创建 test_that 代码块，其中包含年份和值的 tibble。调用函数并存储结果。使用 expect_equal 检查行数，使用带容差的 expect_equal 检查增长值，并使用 expect_true 检查 NA。

renv 依赖管理

项目设置：

调用 renv::init 进行初始化。调用 renv::install 安装 tidyverse 和 shiny 包。调用 renv::snapshot 记录状态。调用 renv::restore 从 lockfile 恢复。

---

高级实现（10 分钟以上）

如需全面了解以下内容：

• 用于异步处理、缓存和部署的高级 Shiny 模式
• 复杂的 ggplot2 扩展和自定义主题
• 使用 dbplyr 和 pool 集成数据库
• R 包开发模式
• 性能优化技术
• 使用 Docker 和 Posit Connect 进行生产部署

请参阅：

• modules/advanced-patterns.md，获取完整的高级模式指南

---

Context7 库映射

• tidyverse/dplyr：数据操作动词
• tidyverse/ggplot2：图形语法可视化
• tidyverse/purrr：函数式编程工具包
• tidyverse/tidyr：数据整理函数
• rstudio/shiny：Web 应用框架
• r-lib/testthat：单元测试框架
• rstudio/renv：依赖管理

---

协同使用效果良好

• moai-lang-python：通过 reticulate 实现 Python 和 R 的互操作
• moai-domain-database：SQL 模式和数据库优化
• moai-workflow-testing：DDD 和测试策略
• moai-essentials-debug：AI 驱动的调试
• moai-foundation-quality：TRUST 5 质量原则

---

故障排除

常见问题：

R 版本检查：

在 R 控制台中调用 R.version.string，检查是否为 4.4 或更高版本。调用 packageVersion 并传入软件包名称，检查已安装的软件包版本。

原生管道无法使用：

• 确保 R 版本为 4.1 或更高，以使用原生管道运算符
• 在 RStudio 的 Tools、Global Options、Code 设置下，检查 Use native pipe 选项

renv 问题：

调用 renv::clean 移除未使用的软件包。调用 renv::rebuild 重建软件包库。调用 renv::snapshot 并将 force 设为 TRUE，以强制更新快照。

Shiny 响应式调试：

将 options shiny.reactlog 设为 TRUE。调用 reactlog::reactlog_enable 启用日志记录。调用 shiny::reactlogShow 显示响应式日志可视化。

ggplot2 字体问题：

加载 showtext 库。调用 font_add_google 并传入字体名称和字体系列。调用 showtext_auto 为所有图形设备启用此功能。

---

最后更新：2026-01-11 状态：活跃（v1.1.0）