ComposeGuard

在 Android Studio 中实时检测 Jetpack Compose 最佳实践和规则违规。

## 预览

## 概述 **ComposeGuard** 是一款 IntelliJ/Android Studio 插件，可在您编写代码时实时检测 Compose 最佳实践违规情况。它会分析您的 composable 函数，并根据 [Compose Rules](https://mrmans0n.github.io/compose-rules/) 文档突出显示相关问题。 无需再等待构建时的 lint 检查或运行时问题，您可以直接在 IDE 中通过视觉指示器、快速修复和详细说明获得即时反馈。 ## 功能 ### 36 条 Compose 规则 ComposeGuard 实现了涵盖 7 个类别的全面规则： | 类别 | 规则 | |----------|-------| | **命名** | Composable 命名、Modifier 命名、CompositionLocal 命名、Preview 命名、Multipreview 命名、Composable 注解命名、事件参数命名 | | **Modifiers** | 必需的 Modifier 参数、Modifier 默认值、Modifier 命名、最外层布局的 Modifier、Modifier 复用、Modifier 顺序、避免使用 composed | | **状态** | 记住状态、特定类型的 mutableStateOf、derivedStateOf 候选项、频繁重组集合、延迟状态读取、状态提升、可变状态作为参数 | | **参数** | 参数顺序、尾随 Lambda 放置、可变类型作为参数、显式依赖项、ViewModel 转发 | | **Composables** | 内容发射、多个内容发射器、内容槽复用、Effect 键、Effect 中的 Lambda 参数、可移动内容、Preview 可见性、LazyList key/contentType 检查 | | **更严格** | Material 2 用法检测、不稳定集合 | ### IDE 集成 - **实时高亮**：在您输入时通过彩色下划线查看违规情况 - **行号图标**：显示每个 composable 函数违规状态的彩色圆点 - 🔴 红色：错误严重性违规 - 🟠 橙色：警告严重性违规 - ⚫ 灰色：弱警告违规 - 🟢 绿色：信息级别违规 - **内联提示**：函数名旁边显示规则违规的小徽章 - **悬停工具提示**：将鼠标悬停在违规项上时显示详细说明 - **快速修复**：针对常见问题的一键修复 (Alt+Enter) ## 安装说明 ### 从 JetBrains Marketplace 安装 [](https://plugins.jetbrains.com/plugin/29308-composeguard) [](https://plugins.jetbrains.com/plugin/29308-composeguard) 1. 打开 Android Studio/IntelliJ IDEA 2. 转到 **Settings** → **Plugins** → **Marketplace** 3. 搜索 "ComposeGuard" 4. 点击 **Install** 或者直接从以下链接安装：[JetBrains Marketplace - ComposeGuard](https://plugins.jetbrains.com/plugin/29308-composeguard) ## 使用说明 安装后，ComposeGuard 会自动分析包含 `@Composable` 函数的 Kotlin 文件。 ### 违规示例 ``` // ❌ Naming violation: Should be PascalCase @Composable fun userCard(user: User) { } // Warning: Should be "UserCard" // ❌ Missing modifier parameter @Composable fun ProductCard(product: Product) { } // Warning: Add modifier parameter // ❌ State not remembered @Composable fun Counter() { val count = mutableStateOf(0) // Error: Wrap in remember { } } // ❌ Unstable collection parameter @Composable fun ItemList(items: List) { } // Warning: Use ImmutableList ``` ### 可用的快速修复 - **重命名 composable** 以遵循命名约定 - **添加 Modifier 参数** 并设置默认值 - **使用 `remember { }` 包装** 状态 - **替换为特定类型的 state**（mutableIntStateOf 等） - **将 Preview 设为 private** - **使用不可变集合** - **抑制规则** 用于故意违规的情况 ## 规则类别 ### 命名规则 | 规则 | 描述 | |------|-------------| | ComposableNaming | 返回 Unit 的 composable 应使用 PascalCase，返回值的应使用 camelCase | | ModifierNaming | Modifier 参数应命名为 `modifier` 或遵循 `xModifier` 模式 | | CompositionLocalNaming | CompositionLocal 属性应以 `Local` 作为前缀 | | PreviewNaming | Preview 函数应遵循命名约定 | | EventParameterNaming | 事件回调应遵循 `onX` 命名模式 | ### Modifier 规则 | 规则 | 描述 | |------|-------------| | ModifierRequired | 发出 UI 的公共 composable 应包含 modifier 参数 | | ModifierDefaultValue | Modifier 参数应具有 `= Modifier` 默认值 | | ModifierTopMost | Modifier 应应用于最外层的布局 | | ModifierReuse | 不要在多个布局中重复使用相同的 modifier | | ModifierOrder | Modifier 链的顺序会影响行为 | | AvoidComposed | 优先使用 `Modifier.Node` 而不是 `composed { }` | ### State 规则 | 规则 | 描述 | |------|-------------| | RememberState | 状态构建器（mutableStateOf 等）应包装在 `remember { }` 中 | | TypeSpecificState | 对基本类型使用 `mutableIntStateOf`、`mutableFloatStateOf` 等 | | DerivedStateOfCandidate | 计算值在适当时应使用 `remember(keys)` 或 `derivedStateOf` | | FrequentRecomposition | 对于频繁更新的 observable 状态源，优先使用感知生命周期的集合 | | DeferStateReads | 在可能的情况下，将快速变化的状态读取延迟到更小的作用域中 | | HoistState | 状态应提升到适当的级别 | | MutableStateParameter | 不要将 MutableState 作为参数传递，应使用值 + 回调 | ### 更严格的规则（默认启用） | 规则 | 描述 | |------|-------------| | Material2Usage | 检测 Material 2 导入，建议迁移到 Material 3 | | UnstableCollections | 标记 `List`、`Set`、`Map` 参数，建议使用 `ImmutableList` 等 | ## 统计仪表板 ComposeGuard 包含一个统计仪表板，用于跟踪项目中的规则违规情况。

### 仪表板功能 - **实时统计**：在编码时查看违规数量 - **类别细分**：按规则类别查看违规分组情况 - **规则级别详情**：深入查看特定规则的违规情况 - **项目概览**：跟踪整体代码质量趋势 从 **View** → **Tool Windows** → **ComposeGuard Statistics** 访问仪表板 ## 配置 ComposeGuard 设置可以按类别进行配置。请访问以下位置进行设置： **Settings** → **Tools** → **ComposeGuard**

### 为现有代码库禁用规则 如果您要将 ComposeGuard 添加到包含遗留代码的现有项目中，您可能需要禁用某些规则以避免出现大量违规提示。操作方法如下： 1. 转到 **Settings** → **Tools** → **ComposeGuard** 2. 您将看到所有带有复选框的规则类别： - **Enable ComposeGuard**：启用/禁用整个插件的主开关 - **Display Options**：切换行号图标和嵌入提示 - **Rule Configuration**：启用/禁用单个规则或整个类别 3. **针对遗留代码库的推荐做法：** - 首先禁用更严格的规则（Material 2 Usage、Unstable Collections） - 在重构代码时逐步启用规则 - 使用类别复选框快速切换整个规则组 - 可以在每个类别内微调单个规则 4. **按文件抑制**：您还可以在代码中使用以下方式抑制特定规则： @Suppress("ComposeGuard:RuleName") @Composable fun MyComposable() { } 根据您的项目需求，打开或关闭单个规则或整个类别。 ## 环境要求 - IntelliJ IDEA 2024.2+ 或 Android Studio Ladybug+ - 已安装 Kotlin 插件 ## 兼容性 | ComposeGuard | IDE 版本 | |--------------|-------------| | 1.2.0 | 2024.2 - 2026.2 | ## 贡献 欢迎贡献！请随时提交 issue 和 pull request。 1. Fork 该仓库 2. 创建您的功能分支 (`git checkout -b feature/amazing-feature`) 3. 提交您的更改 (`git commit -m 'Add amazing feature'`) 4. 推送到该分支 (`git push origin feature/amazing-feature`) 5. 打开一个 Pull Request ## 致谢 此插件基于 [Mrmans0n](https://github.com/mrmans0n) 编写的优秀 [Compose Rules](https://mrmans0n.github.io/compose-rules/) 文档。 ## 许可证 ``` Designed and developed by 2025 androidpoet (Ranbir Singh) Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ```

由 androidpoet 用 ❤️ 打造

标签：Android, Android Studio, Compose, ComposerGuard, Compose Rules, DSL, IDE插件, IntelliJ IDEA, Jetpack Compose, Kotlin, Lint, Modifier, Naming, State, 代码审查, 代码规范, 威胁情报, 安卓开发, 实时检测, 开发者工具, 最佳实践, 移动开发, 错误基检测, 静态代码分析