从能运行到可维护：全栈项目的质量保障清单

功能完成不等于项目完成#

一个页面在本机打开，只能证明 happy path 暂时可用。真正的交付还要面对非法输入、网络失败、重复请求、权限差异、数据迁移和上线后的故障定位。独立开发意味着这些问题也必须由我负责。

类型与边界#

项目使用 TypeScript 与 Zod 同时约束编译期和运行时数据。API 输入先校验，服务层使用 Result 返回可预期业务错误，数据库访问集中在 data 层。这样能让错误尽早暴露，也能避免界面、业务和 SQL 互相渗透。

测试策略#

• 工具函数使用单元测试覆盖边界条件。
• 文章、标签、评论等核心流程使用 D1 集成测试。
• 发布前运行类型检查、lint、格式检查和生产构建。
• 关键页面进行桌面与移动端浏览器验收。

可观测性与性能#

结构化 JSON 日志记录错误类型和上下文，便于在 Workers Observability 中搜索。缓存采用 CDN、KV、D1 多层策略，并通过版本化 key 处理失效。内容发布时预生成公开快照，将高亮等计算从读取链路移到写入链路。

上线前检查清单#

1. 环境变量是否完整且没有把密钥打进客户端包。
2. 数据库迁移是否可重复执行并有备份与回滚方案。
3. 错误页、空状态、权限拒绝和限流反馈是否可理解。
4. SEO、站点地图、RSS、响应式和基础可访问性是否通过检查。

最后#

我理解的独立开发，不是一个人写完所有代码，而是能对完整结果负责：知道哪里可能坏、如何验证、如何观察，以及出现问题时如何恢复。