第26章 编写高质量的代码示例

写作良好的代码示例

编写优秀的代码示例并不容易。学习实用原则，帮你写出专注、易读且可维护的 Flutter 代码示例。

Brett Morgan 2021年8月23日 · 3 分钟阅读

rss_feed 在 X 上分享 在 Bluesky 上分享 在 LinkedIn 上分享

编写优秀的代码示例确实很有难度。让我澄清一下：快速整理一个演示 API 用法或展示 UI 习语的示例，其实可以很轻松。真正的难点在于，你需要向代码仓库额外添加哪些内容，才能让代码示例保持新鲜感并持续吸引开发者。

首先，要在代码中加入一份优秀的 README，开头概括开发者为什么要花时间精力去研究和理解这个示例。随后附上使用说明，并链接到 issue tracker，方便开发者提 bug 或就令人困惑之处提问，这是极好的下一步。

接下来，关注代码本身。代码是否遵循了布局和使用的规范？这可能简单到决定代码放哪里，也可能复杂到涉及 linter 等工具的适当配置。我偏爱那些在代码格式化、布局和 lint 规则集上拥有强标准的编程语言社区。这些标准统一了代码的外观和感觉，使其更易于浏览。为了强制执行 Dart 和 Flutter 的代码格式化，你可以向 CI 管道添加以下命令，若未正确格式化则使构建失败：

bash $ dart format --output none --set-exit-if-changed .

在代码格式化之后，下一步是强制推行一套良好的 lint 规则。对于 Dart，我强烈推荐查看 lints 包；对于 Flutter，我也推荐 flutter_lints 包。为确保 lint 在 CI 管道中通过，请添加以下命令：

bash $ dart analyze

测试。哦，那么多测试。单元测试、集成测试，对于 Flutter 还有 Widget 测试。测试对示例很有价值，因为它们传达了代码预期的使用方式。配合上述提到的 CI 管道，测试还能保持代码库常青。要了解 Flutter 测试功能的更多知识，可以参考 How to test a Flutter app codelab。Dart 和 Flutter 的 CI 命令分别为：

bash $ flutter test # 针对 Flutter 项目 $ dart test # 针对纯 Dart 项目

如果你的代码仓库托管在 GitHub 上，我建议你为 Dart 项目使用 Dart Setup action，为 Flutter 项目使用 Flutter Action。为了获得更多积分，可以考虑添加 Very Good Coverage action 以维持高测试覆盖率。既然已经走了这么远，你大概应该用一个 workflow status badge 来宣传你的 CI 状态。

希望上述添加项清单能指导你使代码示例对目标受众更有价值。

Flutter 更多文章

我如何将 GenLatte 转换为全栈 Dart 并减少了应用服务器账单

Craig Labenz 2026年9月22日 · 7 分钟阅读

快速、可靠的 A2UI 客户端侧函数计算

学习客户端侧函数如何允许代理将本地操作直接委托给在用户设备上运行的 Dart 代码。

Andrew Brogdon 2026年8月28日 · 5 分钟阅读