Animeko 代码风格与协作规范实践：EditorConfig 格式化、Kotlin 官方风格与 PR Review 惯例

• 音视频
• 移动开发
• 视频

本文基于docs/contributing/code-style.md，结合仓库根目录的.editorconfig与相关开发文档，系统讲解 Animeko（Ani，100% Kotlin/Compose Multiplatform 弹幕追番应用）的代码风格统一方案、提交时自动格式化配置，以及面向多平台 Kotlin 仓库的 PR Review 协作惯例。读完本文，你将掌握如何让本地代码自动贴合仓库规范、理解 Kotlin 专属格式化规则的细节，并学会在 PR 评审中正确处理评审意见。

为什么需要统一的代码风格

Animeko 是一个跨 Android / Desktop / iOS 平台的 Kotlin Multiplatform 项目，仓库规模庞大：app/shared下划分了ui-foundation、ui-settings、ui-subject、video-player、datasource、torrent、utils等数十个模块，每个模块又按commonMain、androidMain、desktopMain、iosMain、skikoMain等源集组织。在多平台、多贡献者的协作环境下，如果每位开发者使用各自的缩进、换行和导入顺序习惯，diff 将被格式噪声淹没，Code Review 将难以聚焦真正的逻辑问题。

因此项目在根目录提供了.editorconfig（见 .editorconfig），用机器可读的规则把格式化统一下来。配合 IDE 的提交时格式化功能，可以在每次 commit 时自动整理代码并更新 copyright 年份，从源头保证仓库风格一致。

基于 .editorconfig 的统一格式化规则

项目根目录的.editorconfig是整套格式规范的"法律文本"。它采用 EditorConfig + IntelliJ 平台专有键（ij_*前缀）的写法，既能让支持 EditorConfig 的编辑器（VS Code、Vim 等）读取基础规则，也能让 IntelliJ IDEA / Android Studio 完整应用精细的格式化策略。

全局基础规则

.editorconfig的第一段[*]定义了所有文件类型的公共基线：

需要注意，全局的indent_style = tab只是基线，各语言段落会覆盖它。例如 Kotlin、Java、XML、JSON、Groovy、Shell 等语言段都改用了空格缩进，真正意义上"用 Tab"的语言其实不多。

Kotlin 专属规则（.kt/.kts）

由于项目主体是 Kotlin，.editorconfig用[{*.kt,*.kts}]段落为 Kotlin 单独定制了规则，几个关键点：

• 缩进与行宽：indent_style = space（空格缩进，覆盖全局的 tab），max_line_length = 120（Kotlin 行宽放宽到 120，高于全局的 100）。
• 风格基准：ij_kotlin_code_style_defaults = KOTLIN_OFFICIAL——即底层以Kotlin 官方代码风格为基准，与官方指南保持一致。
• 尾随逗号：ij_kotlin_allow_trailing_comma = true且ij_kotlin_allow_trailing_comma_on_call_site = true，声明与调用点都允许（也推荐）使用尾随逗号，便于多行参数增删。
• 导入顺序：ij_kotlin_imports_layout = *, java.**, javax.**, kotlin.**, ^，即普通导入在前，随后依次是java.**、javax.**、kotlin.**分组，^表示分组之间空一行；同时ij_kotlin_import_nested_classes = false（不自动导入嵌套类）。
• 禁用星号导入：ij_kotlin_name_count_to_use_star_import与ij_kotlin_name_count_to_use_star_import_for_members均设为2147483647，实际效果是几乎永远不会自动折叠为import xxx.*，保持显式导入。
• 多行参数换行：ij_kotlin_call_parameters_wrap = on_every_item、ij_kotlin_method_parameters_wrap = on_every_item，且左括号后换行（ij_kotlin_call_parameters_new_line_after_left_paren = true）、右括号单独一行（ij_kotlin_call_parameters_right_paren_on_new_line = true），if/when/for/while的条件括号前保留空格。
• 空行与换行：ij_kotlin_keep_blank_lines_in_code = 2、ij_kotlin_keep_blank_lines_in_declarations = 2，ij_kotlin_keep_line_breaks = true保留已有换行。

这些规则直接决定了你在 IDE 中按下 Reformat 后代码的最终形态，例如多参数函数调用会呈现"每个参数一行"的垂直布局，导入区按普通 → java → javax → kotlin分组排序。

其他语言段落一览

仓库不止有 Kotlin，.editorconfig还覆盖了项目用到的其他文件类型：

• Java（[*.java]）：空格缩进；命名约定上ij_java_subclass_name_suffix = Impl、ij_java_test_name_suffix = Test；导入顺序按$android.** → $androidx.** → … → 普通导入的固定分组排列。
• XML（*.xml等）：空格缩进，属性保持name="value"形式。
• JSON / HAR（*.json）：空格缩进 2，对象与数组按"每项一行"展开。
• YAML / properties / proto / Markdown / Shell / C/C++ / Groovy / TOML：均各自定义了缩进、空行与空格策略，例如 Markdown 强制标题符号、列表符号后保留一个空格（ij_markdown_force_one_space_after_header_symbol、ij_markdown_force_one_space_after_list_bullet），并格式化表格。

正因为规则覆盖如此全面，才保证了从 Kotlin 源码到 Gradle 配置（.kts）、CI 脚本（.sh）、文档（.md）全链路风格统一。

配置提交时自动格式化与 copyright 更新

代码风格文档强调：在 IDE 的 Commit 页面点击右下角设置，按文档配图（formatting.png）所示配置后，每次提交都会自动格式化代码并更新 copyright 年份。这是把"格式化"从手动动作变成"提交流水线"的关键一步，避免开发者忘记 Reformat。

[!IMPORTANT] 确保 IDE 设置中Editor -> Code Style -> Enable EditorConfig support是勾选的，否则 IDE 不会读取.editorconfig中的规则，格式化结果可能与 CI / 他人环境不一致。

关于 copyright 年份：仓库内源码普遍带有版权头注释，例如第三方模块 Placeholder.kt 开头的Copyright 2021 The Android Open Source Project。开启提交时更新功能后，这类头部中的年份会在 commit 时自动同步为当前年份，避免手工修改。

以 Kotlin 官方风格为基准的代码规范

文档明确了两条代码规范参考：

1. Kotlin 官方代码风格指南：命名、声明布局、控制流写法等一律以官方惯例为准。这与.editorconfig中ij_kotlin_code_style_defaults = KOTLIN_OFFICIAL的设置相互印证——IDE 的自动格式化本质上就是在落实官方风格。
2. Google The Standard of Code Review：评审者与被评审者都应遵循业界通行的 Code Review 标准，关注设计、可读性、可测试性，而不是揪着风格细节不放（风格问题交给格式化工具解决）。

此外文档提出一条硬性要求：请为新功能增加单元测试。这与 testing.md 中的建议一致——"我们建议你为所有新功能编写测试，不仅是为了验证功能的正确性，也是为了防止未来出现回溯问题"。该项目的多平台测试体系相当完善：启用 iOS 目标后 macOS 上会运行 11,000+ 个测试；测试源集按commonTest → jvmTest/desktopTest/androidDeviceTest → nativeTest/appleTest/iosTest → skikoTest分层组织（详见 kmp.md），绝大多数测试应写在commonTest以便所有平台共享执行。日常开发只需保证./gradlew check通过即可 push 与提交 PR。

PR Review 惯例：如何正确回应评审意见

多人协作的仓库中，评审意见的数量和颗粒度差异很大。文档给出了 Animeko 社区约定俗成的处理规则，这也是 contributing README 中"PR 审核"一节直接指向的内容：

"nit: " 前缀表示轻微问题

• 评审者会尽其所能提供反馈，一个 PR 可能收到几个到数十个评论，这些评论可能是必须修改的问题，也可能只是轻微建议。
• 以nit:开头的评论表示轻微问题：当前代码可以接受，只是存在更好的写法，下次可以改进。开发者可以直接忽略这类评论（点击 "Resolve Conversation"）以节约双方时间。

其他评论的通用解决规则

• 按照评论内容修改代码 → commit → push。如果你比较确定这个修改是正确的，直接点击 "Resolve Conversation" 关闭该对话。
• 如果不确定修改是否正确，可以在评论中回复 "done"，提醒审核者仍需关注这条评论，由审核者最终确认。
• 任何时候回复评论后都不要点击 "Resolve Conversation"，否则可能导致审核者错过你的回复——这是最容易踩的协作"坑"：回复即默认需要审核者回看，主动 Resolve 会静默终结对话。

这套惯例把"必须改"和"可以不改"明确分层，既尊重评审者的专业性，也保护开发者的效率，是大规模开源协作中非常务实的做法。

相关文档导航

如果你是初次参与 Animeko 开发，建议按 docs/contributing/README.md 的引导顺序阅读：

1. setup.md：开发工具（IDE、JDK）环境准备
2. code-style.md：本文主题，代码风格与规范
3. architecture.md：项目架构
4. building.md：如何编译与打包 APK
5. testing.md：如何编写测试与调试 APP
6. dev-tips.md：开发提示（如 Compose UI 预览）

小结

Animeko 的代码风格治理可以总结为"一条基线、一个开关、一套惯例"：以.editorconfig为统一基线（Kotlin 走官方风格、120 行宽、尾随逗号、分组导入）；打开 IDE 的 EditorConfig 支持并在提交时自动格式化、更新 copyright；再配合nit:前缀分级与 Resolve Conversation 的回应规则，让格式问题交给工具、让评审聚焦逻辑。对于任何 Kotlin Multiplatform 仓库，这套"EditorConfig + 提交时格式化 + 明确评审符号"的组合都值得直接复用。

• 音视频
• 移动开发
• 视频