Back to Details

dart-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dart Best Practices

Dart开发最佳实践

1. When to use this skill

1. 何时使用此技巧

Use this skill when:
  • Writing or reviewing Dart code.
  • Looking for guidance on idiomatic Dart usage.
在以下场景使用本技巧：
  • 编写或评审Dart代码时。
  • 寻求符合Dart语言习惯的使用指导时。

2. Best Practices

2. 最佳实践

Multi-line Strings

多行字符串

Prefer using multi-line strings (
'''
) over concatenating strings with 
+
and 
\n
, especially for large blocks of text like SQL queries, HTML, or PEM-encoded keys. This improves readability and avoids 
lines_longer_than_80_chars
lint errors by allowing natural line breaks.
Avoid:
dart
final pem = '-----BEGIN RSA PRIVATE KEY-----\n' +
    base64Encode(fullBytes) +
    '\n-----END RSA PRIVATE KEY-----';
Prefer:
dart
final pem = '''
-----BEGIN RSA PRIVATE KEY-----
${base64Encode(fullBytes)}
-----END RSA PRIVATE KEY-----''';
优先使用多行字符串（
'''
）而非通过
+
和
\n
拼接字符串，尤其是处理SQL查询、HTML或PEM编码密钥等大段文本时。这提升了可读性，并且通过自然换行避免了
lines_longer_than_80_chars
的Lint错误。
应避免：
dart
final pem = '-----BEGIN RSA PRIVATE KEY-----\n' +
    base64Encode(fullBytes) +
    '\n-----END RSA PRIVATE KEY-----';
推荐：
dart
final pem = '''
-----BEGIN RSA PRIVATE KEY-----
${base64Encode(fullBytes)}
-----END RSA PRIVATE KEY-----''';

Robust extractions of values from a Map with Switch Expressions

使用Switch表达式从Map中安全提取值

When parsing 
Map
structures or JSON (e.g., from 
jsonDecode
), use switch expressions with object patterns for deep validation and extraction. This is clearer and safer than manual 
is
checks or 
as
casts.
Avoid (Unsafe Access):
dart
final json = jsonDecode(stdout);
if (json is Map &&
    json['configuration'] is Map &&
    json['configuration']['properties'] is Map &&
    json['configuration']['properties']['core'] is Map) {
  return json['configuration']['properties']['core']['project'] as String?;
}
return null;
Prefer (Deep Pattern Matching):
dart
return switch (jsonDecode(stdout)) {
  {
    'configuration': {
      'properties': {'core': {'project': final String project}},
    },
  } =>
    project,
  _ => null,
};
This pattern cleanly handles deeply nested structures and nullable fields without the complexity of verbose 
if-else
blocks or the risk of runtime cast errors.
解析
Map
结构或JSON（例如通过
jsonDecode
获取的内容）时，使用带对象模式的switch表达式进行深度验证和提取。这比手动
is
检查或
as
类型转换更清晰、更安全。
应避免（不安全的访问方式）：
dart
final json = jsonDecode(stdout);
if (json is Map &&
    json['configuration'] is Map &&
    json['configuration']['properties'] is Map &&
    json['configuration']['properties']['core'] is Map) {
  return json['configuration']['properties']['core']['project'] as String?;
}
return null;
推荐（深度模式匹配）：
dart
return switch (jsonDecode(stdout)) {
  {
    'configuration': {
      'properties': {'core': {'project': final String project}},
    },
  } =>
    project,
  _ => null,
};
这种模式无需冗长的
if-else
块，也不会有运行时类型转换错误的风险，能清晰处理深度嵌套结构和可空字段。

Line Length

行长度

Avoid lines longer than 80 characters, even in Markdown files and comments. This ensures code is readable in split-screen views and on smaller screens without horizontal scrolling.
Prefer: Target 80 characters for wrapping text. Exceptions are allowed for long URLs or identifiers that cannot be broken.
即使在Markdown文件和注释中，也要避免行长度超过80个字符。这确保代码在分屏视图和小屏幕上无需横向滚动即可阅读。
推荐： 目标行长度为80个字符时换行。对于无法拆分的长URL或标识符，可以例外。