Back to Details

flutter-codebase-conventions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Flutter Codebase Conventions

Flutter 代码库约定

New code should look like it belongs to the existing project.
This skill governs how code is written or reviewed for consistency. It does not grant permission to modify files during a read-only audit.
新增代码应当看起来天然属于现有项目。
本Skill用于管控代码编写或评审的一致性，不授予在只读审计期间修改文件的权限。

Reuse before create

先复用，后创建

Before creating a new:
  • widget
  • button
  • card
  • dialog
  • bottom sheet
  • input
  • service
  • repository
  • helper
  • extension
  • utility
  • formatter
  • validator
  • error/result type
  • platform abstraction
  • localization helper
  • persistence helper
  • navigation helper
search the codebase for existing functionality serving the same role.
Search by:
  • role/responsibility
  • type/class suffix
  • related feature
  • shared/common/core directories
  • likely call sites
  • naming variants
Do not search only for the exact name you expect.
Read likely matches before deciding to create something new.
在创建新的以下内容之前：
  • Widget
  • 按钮
  • 卡片
  • 对话框
  • 底部面板
  • 输入框
  • 服务
  • 仓库
  • 辅助类
  • 扩展
  • 工具类
  • 格式化器
  • 验证器
  • 错误/结果类型
  • 平台抽象
  • 本地化辅助类
  • 持久化辅助类
  • 导航辅助类
请在代码库中搜索是否已有承担相同角色的功能。
搜索方式包括：
  • 角色/职责
  • 类型/类后缀
  • 相关功能
  • shared/common/core 目录
  • 可能的调用位置
  • 命名变体
不要只搜索你预期的精确名称。
在决定创建新内容之前，请先阅读可能匹配的现有代码。

Semantic equivalence before reuse

复用前先确认语义等价

Similarity is not enough.
Before reusing, extending, or consolidating two implementations, determine whether they actually have the same semantics and reasons to change.
Check:
  • expected behavior
  • callers
  • state/lifecycle assumptions
  • error behavior
  • persistence/network semantics
  • localization requirements
  • platform differences
  • feature-specific rules
  • future change pressure
Two components can look nearly identical while representing different responsibilities.
Do not merge them merely because their current implementation is similar.
相似性是不够的。
在复用、扩展或合并两个实现之前，请先确认它们是否确实具有相同的语义和变更原因。
检查项：
  • 预期行为
  • 调用方
  • 状态/生命周期假设
  • 错误行为
  • 持久化/网络语义
  • 本地化要求
  • 平台差异
  • 功能特定规则
  • 未来变更压力
两个组件可能看起来几乎完全相同，但承担的职责不同。
不要仅仅因为当前实现相似就合并它们。

Reuse vs extend vs create fresh

复用 vs 扩展 vs 全新创建

Prefer reuse when an existing component already matches the required role and semantics.
Prefer extension only when the existing abstraction remains coherent.
Before extending a shared component, verify:
  • existing callers keep their behavior unchanged
  • the new behavior remains generic
  • the API does not become flag-heavy or branch-heavy
  • feature-specific concepts do not leak into shared code
  • the abstraction still has one understandable responsibility
  • regression risk to existing callers is acceptable
Warning signs of a forced extension include:
  • multiple booleans controlling unrelated behavior
  • feature names appearing in shared APIs
  • many conditional branches for individual callers
  • unrelated optional parameters
  • callers needing special-case knowledge
If satisfying one new caller would distort the shared abstraction, prefer a focused new component.
Reuse is a means to consistency and maintainability, not a goal by itself.
当现有组件已经符合所需的角色和语义时，优先复用。
仅当现有抽象仍保持内聚性时，才优先选择扩展。
在扩展共享组件之前，请验证：
  • 现有调用方的行为保持不变
  • 新行为保持通用性
  • API 不会变得充满标志位或分支
  • 功能特定的概念不会泄漏到共享代码中
  • 该抽象仍然只有一个清晰易懂的职责
  • 对现有调用方的回归风险在可接受范围内
强行扩展的警告信号包括：
  • 多个布尔值控制不相关的行为
  • 共享API中出现功能名称
  • 为单个调用方设置大量条件分支
  • 不相关的可选参数
  • 调用方需要了解特殊情况
如果满足一个新调用方的需求会扭曲共享抽象，请优先创建一个专注于特定需求的新组件。
复用是实现一致性和可维护性的手段，而非目的本身。

Shared vs feature-local

共享 vs 功能本地

Do not move code into shared/core solely because more than one feature uses it.
Promote functionality when the responsibility is genuinely shared and stable.
Keep functionality feature-local when:
  • semantics differ by feature
  • the abstraction would need feature-specific branches
  • future changes are likely to diverge
  • sharing would increase coupling
  • the shared API would become harder to understand than the local code
A small amount of duplication may be safer than premature centralization.
不要仅仅因为多个功能使用某段代码，就将其移到 shared/core 目录。
当职责确实是共享且稳定的，才将功能提升为共享。
在以下情况下，请将功能保留在功能本地：
  • 语义因功能而异
  • 抽象需要功能特定的分支
  • 未来变更可能会出现分歧
  • 共享会增加耦合度
  • 共享API比本地代码更难理解
少量的重复可能比过早的集中更安全。

House style

项目风格

Match existing project conventions when they are coherent and intentional.
Consider:
  • file naming
  • folder organization
  • Page vs Screen naming
  • imports
  • state-management approach
  • dependency injection
  • routing
  • models
  • error handling
  • widget composition
  • theme usage
  • repository/service boundaries
  • async patterns
  • testing style
Do not introduce a competing architectural pattern without a concrete reason.
Do not force every feature into identical structure when the project already contains legitimate feature-specific differences.
当现有项目约定是清晰且有意为之的，请遵循这些约定。
考虑以下方面：
  • 文件命名
  • 文件夹组织
  • Page 与 Screen 命名
  • 导入方式
  • 状态管理方案
  • 依赖注入
  • 路由
  • 模型
  • 错误处理
  • Widget 组合
  • 主题使用
  • 仓库/服务边界
  • 异步模式
  • 测试风格
没有具体理由的情况下，不要引入相互冲突的架构模式。
当项目已经存在合理的功能特定差异时，不要强制每个功能都采用相同的结构。

Styling

样式

Prefer existing:
  • theme
  • typography
  • spacing
  • colors
  • radius
  • component patterns
Avoid hardcoded values when an appropriate shared value already exists.
Do not introduce a new design-token system merely because one does not exist.
Do not force a shared style abstraction for values that are legitimately feature-specific.
优先使用现有的：
  • 主题
  • 排版
  • 间距
  • 颜色
  • 圆角
  • 组件模式
当已经存在合适的共享值时，避免使用硬编码值。
不要仅仅因为不存在设计令牌系统就引入新的系统。
不要为确实属于功能特定的值强制创建共享样式抽象。

Assets

资源（Assets）

Never invent an asset path.
Confirm:
  • the asset exists
  • the declared path is correct
  • pubspec.yaml
    includes it when needed
  • platform-specific assets are placed appropriately
If an asset is missing, report that instead of assuming it exists.
永远不要臆造资源路径。
请确认：
  • 资源确实存在
  • 声明的路径正确
  • 需要时已在 
    pubspec.yaml
    中声明
  • 平台特定的资源放置在正确的位置
如果缺少资源，请报告该问题，而不是假设它存在。

Dependencies

依赖

Before adding a package:
  • check whether the project already solves the problem
  • check whether Flutter/Dart itself reasonably solves it
  • check whether an existing dependency already provides the capability
  • consider maintenance status when materially relevant
  • consider package size/platform impact when materially relevant
  • consider license when relevant to distribution
Do not recommend replacing a dependency merely because another package is newer, more popular, or more fashionable.
A dependency is a problem only when there is a concrete project-level reason, such as:
  • unsupported target platform
  • unresolved compatibility issue
  • known production defect affecting this project
  • abandonment that creates a real maintenance/release risk
  • duplicate dependency roles with meaningful cost or inconsistency
在添加新包之前：
  • 检查项目是否已经解决了该问题
  • 检查 Flutter/Dart 本身是否能合理解决该问题
  • 检查现有依赖是否已经提供了该能力
  • 相关时考虑维护状态
  • 相关时考虑包大小/平台影响
  • 与分发相关时考虑许可证
不要仅仅因为另一个包更新、更流行或更时髦就推荐替换现有依赖。
只有当存在具体的项目级原因时，依赖才是一个问题，例如：
  • 不支持目标平台
  • 未解决的兼容性问题
  • 影响本项目的已知生产缺陷
  • 项目被弃用，带来实际的维护/发布风险
  • 依赖角色重复，带来显著的成本或不一致性

Duplication

重复代码

Flag meaningful duplication, not visual or textual similarity.
Meaningful duplication is duplication that creates realistic risk of:
  • inconsistent behavior
  • repeated bug fixes
  • divergent business rules
  • multiple sources of truth
  • inconsistent UI behavior
  • duplicated platform logic
  • conflicting persistence/network handling
  • unnecessary maintenance burden
Do not create an abstraction merely to remove a few duplicated lines.
请标记有实际意义的重复，而非视觉或文本上的相似。
有实际意义的重复是指会产生以下现实风险的重复：
  • 行为不一致
  • 重复修复Bug
  • 业务规则分歧
  • 多真值源
  • UI行为不一致
  • 平台逻辑重复
  • 持久化/网络处理冲突
  • 不必要的维护负担
不要仅仅为了消除几行重复代码就创建抽象。

Intentional duplication and migration states

有意重复与迁移状态

Before reporting duplication, check whether multiple implementations are intentional.
Examples:
  • old/new implementation during migration
  • platform-specific implementations
  • experiment/feature-flag variants
  • compatibility layer
  • deprecated code still serving older flows
  • test-only implementation
  • temporary adapter during refactor
Do not consolidate intentional parallel implementations without understanding their lifecycle and callers.
If duplication appears temporary, identify whether cleanup is actually due before reporting it as a production issue.
在报告重复之前，请检查多个实现是否是有意为之的。
例如：
  • 迁移期间的旧/新实现
  • 平台特定的实现
  • 实验/功能开关变体
  • 兼容层
  • 仍为旧流程服务的已弃用代码
  • 仅用于测试的实现
  • 重构期间的临时适配器
在不了解其生命周期和调用方的情况下，不要合并有意并行的实现。
如果重复看起来是临时的，请在报告为生产问题之前确认清理工作是否确实已到期。

Full-project consistency review

全项目一致性评审

During a full-project production audit, inspect consistency across features rather than only files already being changed.
Use search before concluding duplication exists.
Look for repeated roles such as:
  • widgets serving the same functional role
  • duplicated business rules
  • repeated validation
  • duplicate formatters/parsers
  • overlapping helpers
  • parallel services/repositories
  • repeated persistence/query logic
  • duplicate API/network handling
  • duplicated error mapping
  • repeated localization helpers
  • duplicate navigation helpers
  • repeated platform abstractions
  • duplicated state ownership
  • multiple sources of truth
  • feature-local implementations of existing shared functionality
For each suspected duplicate, inspect callers and semantics before reporting it.
在全项目生产审计期间，要检查跨功能的一致性，而不仅仅是已修改的文件。
在得出存在重复的结论之前，请使用搜索功能。
寻找重复的角色，例如：
  • 承担相同功能角色的Widget
  • 重复的业务规则
  • 重复的验证逻辑
  • 重复的格式化器/解析器
  • 重叠的辅助类
  • 并行的服务/仓库
  • 重复的持久化/查询逻辑
  • 重复的API/网络处理
  • 重复的错误映射
  • 重复的本地化辅助类
  • 重复的导航辅助类
  • 重复的平台抽象
  • 重复的状态所有权
  • 多真值源
  • 现有共享功能的功能本地实现
对于每个疑似重复项，在报告之前请检查其调用方和语义。

Convention drift

约定漂移

During a full-project review, look for meaningful convention drift.
Examples:
  • error handling
  • dependency injection
  • repository boundaries
  • state ownership
  • loading/failure representation
  • localization
  • theme/style usage
  • navigation
  • persistence access
  • platform-service access
  • logging
  • serialization
Do not report harmless stylistic differences.
Distinguish:
  • style drift
  • structural drift
  • behavior drift
Style drift alone is usually low-value unless it causes maintenance or readability problems.
Behavior drift is more important when equivalent responsibilities now behave differently.
Report convention drift only when it creates a realistic:
  • correctness problem
  • maintenance burden
  • duplication risk
  • testing inconsistency
  • UX inconsistency
  • architectural confusion
在全项目评审期间，寻找有实际意义的约定漂移。
例如：
  • 错误处理
  • 依赖注入
  • 仓库边界
  • 状态所有权
  • 加载/失败表示
  • 本地化
  • 主题/样式使用
  • 导航
  • 持久化访问
  • 平台服务访问
  • 日志
  • 序列化
不要报告无足轻重的风格差异。
请区分：
  • 风格漂移
  • 结构漂移
  • 行为漂移
仅风格漂移通常价值较低，除非它导致了维护或可读性问题。
当等效职责现在的行为不同时，行为漂移更为重要。
仅当约定漂移会产生现实的以下问题时，才报告：
  • 正确性问题
  • 维护负担
  • 重复风险
  • 测试不一致
  • UX不一致
  • 架构混乱

Consistency vs correctness

一致性 vs 正确性

Do not change correct behavior merely to make code look more uniform.
Consistency is secondary to:
  • correctness
  • product semantics
  • platform behavior
  • feature-specific requirements
If two patterns are both valid and already established, do not force convergence without clear benefit.
不要仅仅为了让代码看起来更统一就改变正确的行为。
一致性次于以下几点：
  • 正确性
  • 产品语义
  • 平台行为
  • 功能特定要求
如果两种模式都是有效的且已经确立，在没有明确收益的情况下，不要强制收敛。

Evidence discipline

证据规范

Do not report duplication or inconsistency solely from names, file structure, or superficial code similarity.
A confirmed duplication finding should identify:
  • the implementations involved
  • their actual responsibility
  • their callers
  • why the semantics overlap
  • the concrete risk created by keeping both
If responsibility or semantics remain unclear, classify the finding as Needs verification or continue investigating.
Do not inflate severity merely because duplicated code exists.
不要仅仅根据名称、文件结构或表面的代码相似性就报告重复或不一致。
一个经过确认的重复发现应当明确：
  • 涉及的实现
  • 它们的实际职责
  • 它们的调用方
  • 语义重叠的原因
  • 保留两者带来的具体风险
如果职责或语义仍不明确，请将发现归类为“需要验证”或继续调查。
不要仅仅因为存在重复代码就夸大严重程度。

Reporting

报告方式

For duplication or consistency findings, report:
  • relevant files/components
  • shared or conflicting responsibility
  • supporting evidence
  • actual risk
  • whether the safer direction is:
    • reuse
    • extension
    • consolidation
    • intentional separation
    • no change
  • confidence in the finding
If the relationship between implementations is unclear, investigate callers and semantics before reporting them as duplicates.
During a read-only audit, report findings only.
Do not consolidate, move, rename, refactor, or restructure code without explicit authorization.
对于重复或一致性发现，请报告：
  • 相关文件/组件
  • 共享或冲突的职责
  • 支持证据
  • 实际风险
  • 更安全的处理方向是：
    • 复用
    • 扩展
    • 合并
    • 有意分离
    • 无需变更
  • 对发现的置信度
如果实现之间的关系不明确，请在报告为重复项之前调查调用方和语义。
在只读审计期间，仅报告发现结果。
未经明确授权，不得合并、移动、重命名、重构或调整代码结构。

Final principle

最终原则

The goal is not maximum reuse.
The goal is:
coherent code with the right boundaries, minimal accidental duplication, and abstractions that remain understandable as the project evolves.
目标不是最大化复用。
目标是：
代码内聚、边界合理、意外重复最少，且抽象在项目演进过程中始终易于理解。