前言
"AI 写的代码不符合项目规范"——这可能是当下开发者使用 AI 辅助编程时最常遇到的问题。
问题的根源不在 AI 的能力，而在于我们没有给 AI 足够清晰的规范。传统项目的"规范"散落在 README、Wiki、代码注释、口头约定中，AI 无法形成完整的理解。
Clhoria 是我基于规范驱动开发（Spec-Driven Development）理念构建的企业级 Hono 后端模板。它的核心目标是：让规范成为项目的一等公民，让 AI 能够深度理解并遵循这些规范，实现真正高效的人机协作开发。
什么是规范驱动开发
规范驱动开发（SDD）颠覆了传统的开发层级关系——让规范成为主导，代码成为规范的实现。
在传统开发流程中，我们先写代码，再补文档，规范往往是事后补充。而 SDD 的顺序是：先定义精确的规范，再基于规范生成代码。这种方式天然适配 AI 辅助开发，因为精确的规范可以直接转化为可工作的代码。
Clhoria 将 SDD 落地为 6 个标准阶段：需求分析与技术架构设计、生成接口代码、生成测试用例、循环优化、验收通过、生成模块文档。每个功能模块完成后，会产出两份文档——spec.md 记录需求与架构决策，module.md 记录模块的文件索引与技术要点，为后续 AI 维护提供完整上下文。
规范如何贯穿 Clhoria 的设计
代码结构即规范
Clhoria 对路由模块的文件结构有明确约定：每个功能模块包含 handlers（业务逻辑）、routes（路由定义与 OpenAPI 规范）、index（统一导出）、types（类型定义）四个必需文件，以及 schema、services、helpers 三个可选文件。
这不是随意的目录划分，而是经过深思熟虑的规范。handlers 专注业务逻辑，保持纯净；routes 定义 OpenAPI 规范，代码即文档；types 集中类型定义，便于 AI 理解数据结构。当 AI 需要新增功能时，它知道应该在哪里添加什么代码。
类型系统即规范
Clhoria 采用 Hono + Zod + TypeScript 的全链路类型推导。Zod Schema 分为两层：DB 层从 Drizzle 表定义生成基础 Schema，路由层继承并组合成业务 Schema。所有字段描述只在 DB 层添加，路由层只负责裁剪和扩展。
这套分层策略让 AI 清楚地知道：需要添加字段描述时去 DB 层，需要组合业务 Schema 时去路由层。类型约束本身就是规范，编译器会强制执行。
权限模型即规范
传统后台系统的权限标识存储在数据库中，容易与代码实现不一致。Clhoria 采用完全不同的思路：API 路由本身就是权限标识。
基于 RESTful 路径和 Casbin KeyMatch3，权限策略直接匹配类似 GET /api/admin/users 这样的路径模式。新增接口时，无需在数据库中添加权限记录，Casbin 策略可以通过通配符自动覆盖。代码即权限，删除路由就删除了权限，不会出现孤儿数据。
同样的理念也应用于菜单系统和字典系统。菜单基于 Refine Resource 在编译时生成，字典基于 TypeScript 枚举映射到 PostgreSQL Enum。单一数据源，改一处全链路同步，TypeScript 编译器会在遗漏更新时报错。
为 AI 协作优化的开发体验
毫秒级热重载与资源管理
Clhoria 基于 Vite 构建开发环境，但后端 HMR 面临资源泄漏的挑战——每次热更新时，旧模块持有的数据库连接、Redis 连接、定时器等资源不会自动释放。
Clhoria 通过单例管理系统统一管理长连接资源，模块卸载时自动清理。同时提供资源监控插件，基于 Node.js 的 getActiveResourcesInfo 接口监控 HMR 前后的系统资源变化，使用滑动窗口检测连续增长趋势，只在累计增长达到阈值时才报警，避免误报干扰开发。
编译时性能优化
在使用 zod-openapi 时，一个常见的性能陷阱是在函数内部定义 Zod Schema，导致每次请求都重新创建对象。Clhoria 提供了一个 Vite 插件，在编译时自动将函数内部的 Schema 定义提升到模块顶部，只创建一次。这个优化对高频接口的性能提升显著，而开发者无需改变编码习惯。
自动路由发现
基于 Vite 的 import.meta.glob 自动扫描路由模块，新增功能只需创建目录结构，无需手动注册。Vite 会自动发现新的 index 文件，配合 HMR 立即生效。这降低了 AI 生成代码后的集成成本——生成的模块放到正确位置就能运行。
企业级能力
Clhoria 不只是一个开发模板，它提供了生产环境所需的完整能力：
JWT 双密钥认证机制实现 Admin 和 Client 的完全隔离；Casbin RBAC 支持角色继承和动态策略更新；基于 pg-boss 的分布式任务队列支持延迟执行、重试策略和 Saga 事务补偿；日志中间件支持阿里云 SLS、TimescaleDB、Loki 等多种存储方案；基于 excelize-wasm 的 Excel 处理拥有 Golang 同款性能。
所有第三方服务依赖（Sentry、Cloudflare R2 等）均为可选，项目可以完全部署在内网环境，技术栈符合信创要求。
与传统方案的差异
传统代码生成器的问题在于：生成的代码是"死"的，缺乏上下文，需要大量手动修改才能融入项目。而且生成器本身需要配置和维护，模板更新后旧代码无法同步。
Clhoria 的 SDD 模式则是让 AI 理解活的规范。CLAUDE.md 配置文件详细描述了项目架构、编码约定、文件组织方式。AI 不是机械地填充模板，而是基于对规范的理解生成符合项目风格的代码。规范更新后，AI 的后续生成自然会遵循新规范。
开发效率的差异更加明显：传统方式需要手工维护接口文档，容易与实现不同步；Clhoria 的 OpenAPI + Zod 方案让代码即文档，类型安全，文档永不过期。传统方式的热更新需要重启服务器等待数秒；Clhoria 的修改毫秒级生效。
快速开始
项目仓库地址：github.com/zhe-qi/clho…
克隆项目后，安装依赖，复制环境变量配置文件，启动开发服务器，即可访问 localhost:9999 查看 API 文档。项目配套的后台管理前端基于 Refine + Shadcn 开发，仓库地址：github.com/zhe-qi/refi…
技术栈基于 Node.js 24+、Hono、Vite、Drizzle ORM、PostgreSQL 18+、Redis 7+，支持实验性的 ts-go 类型检查以获得更好的性能。
写在最后
规范驱动开发不是一个新概念，但在 AI 时代它获得了新的生命力。当规范足够精确和完整时，AI 就能从"勉强能用"变成"真正好用"。
Clhoria 是这个理念的一次实践。如果你正在探索 AI 辅助开发的最佳姿势，或者需要一个现代化的企业级后端起点，欢迎尝试。
QQ 交流群：1076889416
