上周我带着团队里的一个新人做项目他吭哧吭哧写了两天跑过来给我看一个功能模块。我让他演示一下他点开一个按钮页面跳转数据加载一切看起来都挺流畅。然后我问他“这个模块的输入边界是什么如果上游接口返回空数组或者超时了这里会怎么处理你试过连续快速点击这个按钮吗日志打在哪里了这个状态管理逻辑如果另一个页面也要用你怎么复用”他愣了一下说“啊我就是想先做个 demo 出来看看效果……”这个场景太典型了。我们每天都在做“demo”无论是验证一个新技术框架还是向老板或客户展示一个初步想法。“做个 demo 看看”几乎是所有开发工作的起点。但问题恰恰在于绝大多数人对于“demo”的理解就停留在了“做个能跑起来的东西”这个层面。于是我们看到了海量的、孤立的、脆弱的代码片段从java controller demo、netty客户端demo到springboot vue 钉钉免登录demo、camera2 mediacodec 推流 demo。这些代码解决了“从 0 到 1 跑通”的问题却把“从 1 到 100 可用”的坑留给了未来的自己或接手的同事。一个高质量的“开发记录”或“demo”其核心价值绝不仅仅是记录“我做了什么”而是清晰地阐述“我为什么这么做以及这么做之后接下来该怎么走”。它应该是一个思维脚手架而不仅仅是一份成果快照。今天我们就以“demo开发记录”为引子拆解一下如何把你的一次性实验代码变成一份有长期价值的、可工程化的资产。1. 重新定义“Demo”从可运行片段到可复现流程当我们搜索java小项目demo或android 画中画demo时我们到底在找什么是一个能直接复制粘贴就能运行的.zip包吗很多时候是。但更本质的我们是在寻找一个“可复现的认知路径”。我们想知道在特定的环境、依赖和约束下达成某个目标的标准步骤和关键决策点是什么。一个仅展示最终效果的 demo就像给你看一道做好的菜却不告诉你火候和调料顺序。而一份好的开发记录应该是一份详细的菜谱甚至包括“如果锅糊了怎么办”、“没有某种调料用什么替代”。1.1 超越“Hello World”构建最小可验证场景很多 demo 始于一个“Hello World”也止于一个“Hello World”。比如netty客户端demo可能就是一个连接服务器、发送一条消息、打印回复然后关闭的循环。这没错但它太“干净”了。一个更有价值的 demo 应该构建一个“最小可验证场景”。这个场景需要包含该技术栈最核心、也最容易出错的环节。以 Netty 客户端为例一个更好的记录结构可能是目标验证在存在网络波动和服务端重启的情况下客户端的重连和消息可靠性机制。场景设计基础连接与消息收发必选。模拟服务端无响应超时触发ReadTimeoutHandler。模拟网络断开验证ChannelFutureListener如何检测并触发重连逻辑。在重连成功后验证业务消息的续发或状态恢复。记录要点不仅仅是代码还有你如何模拟“网络断开”是拔网线还是用iptables丢包。关键 Handler 的添加顺序和原因为什么IdleStateHandler要放在ReadTimeoutHandler前面。重连策略的代码指数退避固定间隔和配置参数最大重试次数、间隔。这样你的 demo 记录就从“功能展示”升级为“问题解决方案验证”价值陡增。1.2 环境与依赖的精确快照避免“在我机器上是好的”“我这里跑得好好的”是软件开发世界最大的谎言之一。你的spring cloud alibaba 配置rocketmq 发送消息demo之所以能跑依赖于特定版本的 Spring Cloud、RocketMQ Client、JDK甚至特定的 Maven 仓库地址。一份负责任的开发记录必须包含一份“环境清单”这比代码本身更重要。这份清单应该像实验室报告一样精确核心依赖及版本不要写spring-boot-starter要写spring-boot-starter:2.7.18。用mvn dependency:tree或gradle dependencies导出关键部分。关键配置application.yml或bootstrap.yml中非默认的、影响功能的配置项。例如 RocketMQ 的name-server地址、生产者组名、发送超时时间。外部服务状态Demo 依赖的 RocketMQ 集群、数据库、Redis 的版本和关键配置。如果是本地 Docker 启动的记录docker-compose.yml或启动命令。系统环境操作系统、JDK 版本java -version、构建工具版本。你可以用一个简单的README.md模板来固化这个清单## 环境要求 - JDK: 11 (Amazon Corretto 11.0.20) - Maven: 3.8.6 - RocketMQ: 4.9.7 (单机 Docker 模式) - Spring Boot: 2.7.18 ## 前置准备 1. 启动 RocketMQ: docker run -d ... 2. 创建 Topic: mqadmin updateTopic ... 3. 修改配置: src/main/resources/application.yml 中的 name-server: 127.0.0.1:9876 ## 如何运行 1. mvn clean spring-boot:run 2. 访问 http://localhost:8080/send?msgtest 发送消息。 3. 查看控制台日志或 RocketMQ 控制台确认消息。2. 记录决策与权衡为什么比是什么更重要代码只体现了“你最终的选择”而开发记录应该揭示“你面临过的所有岔路口和选择的原因”。这是新手和资深开发者在撰写记录时最核心的差异。2.1 技术选型的理由在你的avalonia 官方demo学习记录里不要只粘贴官方教程的代码。要记录为什么选择 Avalonia是因为需要跨平台Windows, macOS, Linux的桌面 UI而 WPF 做不到还是看中了它的性能或与 .NET 生态的融合度在 MVVM 框架选择上是用了 ReactiveUI 还是社区别的框架为什么是看中了响应式编程的便利还是为了保持项目结构简单与 Electron 或 Flutter 的对比哪怕只是初步了解记录下你当时查到的、影响你决策的关键点如安装包大小、内存占用、开发语言偏好等。这些记录在未来技术复盘、方案评审或向他人解释时是无价的上下文信息。2.2 关键参数与配置的注释很多问题隐藏在配置里。比如camera2 demo中配置ImageReader获取预览帧时ImageReader.newInstance(previewSize.getWidth(), previewSize.getHeight(), ImageFormat.YUV_420_888, 2);那个数字2是什么意思它代表最大缓冲图像数量。为什么是 2 不是 5 或 10因为对于预览来说2 通常足够一个在显示一个在排队设置更大可能会增加内存消耗和延迟。如果你的 Demo 目标是高帧率录制你可能需要更大的缓冲区来防止丢帧。在你的记录里对于每一个你不假思索从 Stack Overflow 复制过来的“魔法数字”或配置项都应该追问一句“为什么是这个值”并记录下来。这能帮你和读者理解系统的行为边界。2.3 遇到的坑与解决方案这是开发记录中最精华的部分。php微信支付v3 demo下载下来跑不通太正常了。你的价值就在于记录下“如何跑通”的过程。现象调用统一下单 API 返回“签名错误”。排查对比官方文档的签名算法步骤。发现 Demo 中获取平台证书的代码逻辑在本地网络环境下有超时可能。证书缓存文件路径权限问题导致无法写入。解决增加了获取证书时的重试机制和超时时间配置。明确了缓存目录需要可写权限并在代码中增加了目录检查。编写了一个独立的verify_signature.php脚本用于对比自己和微信官方验签工具的结果进行逐步调试。把这些坑和填坑的过程记下来这个 Demo 就从“别人的代码”变成了“你深刻理解后的资产”。3. 从演示到工程化补上那些“Demo”里没有的环节一个只能由原作者在特定环境下点击运行的 Demo其工程价值为零。工程化的核心是让过程变得可靠、可重复、可协作。你的开发记录应该引导读者向这个方向思考。3.1 输入验证与边界处理回顾开头我那个新同事的例子。他的 Demo 假设所有输入都是理想的。但真实世界充满意外。在你的java controller demo里那个接收RequestBody的接口有没有用Valid做校验参数为空、为 null、类型不对、超出范围时返回什么是通用的 400 Bad Request还是带有明确错误码和信息的业务响应文件上传 Demo (springboot vue常见)有没有检查文件大小、类型、病毒上传失败是整体回滚还是部分保存在你的记录中应该有一节专门写“健壮性考虑”哪怕你只是列出了 TODO。例如已知缺陷与改进点UserController#create接口未对email字段进行格式校验。文件上传接口未设置大小限制存在内存溢出风险。所有异常目前均返回500 Internal Server Error需细化为业务异常和系统异常。3.2 可观测性日志、监控与调试Demo 通常只关心主流程不关心“发生了什么”。但排错全靠猜。日志关键的业务节点开始处理、调用外部服务、成功结束、分支判断if-else、异常捕获处必须打日志。记录你用了什么日志框架SLF4J Logback日志级别如何配置INFO, DEBUG, ERROR日志输出到了哪里控制台、文件/logs/app.log。链路追踪在微服务 Demo (spring cloud alibaba) 中是否集成了 Sleuth 或 SkyWalking让一个请求穿过多个服务时依然能被追踪状态暴露是否有一个简单的/health或/metrics端点用于检查应用健康状态和基本指标如 RocketMQ 发送消息的成功率在你的开发记录里加入一个“如何排查常见问题”的章节告诉读者当 Demo 不工作时第一步看什么日志文件第二步检查什么配置第三步如何调试。3.3 自动化与脚本化“一键运行”是降低他人使用成本的关键。这不仅仅是mvn spring-boot:run。构建脚本除了 Maven/Gradle是否有脚本处理环境变量比如run.sh或start.bat里面设置了JAVA_OPTS、SPRING_PROFILES_ACTIVE。数据准备Demo 需要的数据库表、初始数据是否通过schema.sql和data.sql自动初始化或者提供一个init_database.sql脚本。测试脚本是否包含一组curl命令或 Postman 集合的导出文件让别人能立刻验证核心接口容器化这是 Demo 工程化的终极形态。一个Dockerfile加上docker-compose.yml能封装所有环境依赖。记录你构建 Docker 镜像的步骤和遇到的坑比如时区问题、权限问题比代码本身更有价值。4. 从记录到资产沉淀模式与知识库当你积累了足够多这样的“增强型 Demo 记录”后你会发现它们开始相互关联形成你自己的知识网络。你需要一个系统来管理这些资产。4.1 建立个人或团队的 Demo 模式库不要每次都是从零开始。为不同类型的 Demo 建立模板Web 后端 API Demo 模板包含统一的响应封装 (ResultT)、全局异常处理 (ControllerAdvice)、参数校验 (Valid)、Swagger/OpenAPI 文档、日志配置和 Dockerfile。前端组件 Demo 模板包含状态管理 (Pinia/Vuex)、路由、API 请求封装 (axios)、UI 库按需引入的配置。移动端功能 Demo 模板包含权限申请模板、网络层封装、本地存储方案、关键生命周期的日志打印。你的每一次新 Demo 开发都基于某个模板进行只关注本次要验证的新技术或新逻辑。这样你的记录就可以聚焦在“差异点”上。4.2 记录的结构化超越纯文本纯文本的README.md很好但可以更好。代码注释与提交信息在代码关键处用注释链接到你的详细设计记录或问题追踪编号如// See design-decisions.md#authentication。提交信息 (Git Commit Message) 要清晰使用 Conventional Commits 格式如feat(camera): add manual focus support。架构图与序列图用 PlantUML、Mermaid 甚至手绘截图描述模块关系和数据流。一张图胜过千言万语尤其是在描述netty的 Handler 流水线或微服务间的调用链时。视频记录对于 UI 交互复杂的 Demo如android 画中画demo一段 30 秒的屏幕录制视频比任何文字描述都直观。你可以把视频上传到内部 Wiki 或云存储在文档中嵌入链接。4.3 定期复盘与更新技术栈会过时依赖会有漏洞。一个被归档的 Demo半年后可能就因为某个依赖的 major version 升级而无法运行。设立“保鲜期”给你的 Demo 仓库打上标签如stable-2024-05。在 README 顶部注明“此 Demo 基于 Spring Boot 2.7.x 构建最后一次验证于 2024年5月。如需在新版本中使用请关注UPGRADE.md文档。”创建升级指南当你有时间时尝试用新技术栈的主要版本升级你的经典 Demo并记录升级过程。比如《将 Spring Boot 2.7 Demo 升级至 3.2 的实践与坑点》。这份记录本身又是一个极具价值的 Demo。知识串联当你写一个新的关于“分布式事务”的 Demo 时你可以在文档中引用之前写的“RocketMQ 消息发送”和“Seata AT 模式”两个 Demo形成知识图谱。最终一份优秀的“demo开发记录”其终点不是一个孤立的、可运行的.zip文件而是一个活的、可生长的、与你的知识体系相连的节点。它始于一次具体的技术验证但通过记录环境、决策、陷阱和工程化思考它变成了一份能穿越时间、降低他人认知负荷、并能反复被你自己引用的高质量资产。下次当你再写下git commit -m “add demo”时不妨先问问自己这份记录除了我还能不能帮助到三个月后遗忘细节的我或者团队里另一位需要解决类似问题的同事如果你的答案是肯定的那么你就已经超越了绝大多数仅仅在“完成任务”的开发者。