dart-best-practices

Dart 最佳实践

1. 何时使用此技能

在以下情况下使用此技能：

• 编写或审查 Dart 代码。
• 查找有关惯用 Dart 用法的指导。

何时不应使用（避免滥用的原则）

在以下情况下，不要应用此技能或重构代码：

• 破坏公共 API 的变更：如果重构会改变已发布软件包的公共 API 合约、 返回类型或参数签名，且没有协调进行 SemVer 主版本升级。
• 教条式微优化：为了微不足道的理论收益而重写清晰、易读的代码（例如， 在简单的单行日志消息中，用多行引号替换清晰的字符串拼接）。
• 特定领域或代码生成的文件：生成的文件（*.g.dart、 *.freezed.dart、protobuf 文件），或行长和字符串布局由代码生成器管理的文件。
• 公共接口中的显式类型注解：在显式类型能够说明公共 API 表面或消除复杂泛型歧义时，不要将其替换为 var 或 final。

2. 最佳实践

多行字符串

优先使用多行字符串（'''），而不是用 + 和 \n 拼接字符串， 尤其是对于 SQL 查询、HTML 或 PEM 编码密钥等大型文本块。这样可提升可读性， 并通过自然换行避免触发 lines_longer_than_80_chars lint 错误。

避免：

final pem = '-----BEGIN RSA PRIVATE KEY-----\n' +
    base64Encode(fullBytes) +
    '\n-----END RSA PRIVATE KEY-----';

推荐：

final pem = '''
-----BEGIN RSA PRIVATE KEY-----
${base64Encode(fullBytes)}
-----END RSA PRIVATE KEY-----''';

行长

避免行长超过 80 个字符，即使是在 Markdown 文件和注释中也是如此。这样可以确保 代码在分屏视图和较小屏幕上都易于阅读，无需水平滚动。

推荐： 文本换行时以 80 个字符为目标。无法拆分的长 URL 或标识符可例外处理。

查找方法

多行字符串

要查找适合改为多行字符串的代码，可搜索包含换行符的字符串拼接：

• 正则表达式：['"]\s*\+\s*['"]
• 正则表达式：\+\s*['"].*\\n

行长

• 依靠 analyzer 的 lines_longer_than_80_chars lint 检查。

相关技能

• dart-modern-features：了解现代 Dart 特性的惯用用法，例如模式匹配（适用于深层 JSON 提取）、Records 和 Switch 表达式。