🚀 核心理念：从代码工程到上下文工程
传统开发模式下，开发者 80% 的时间在写重复代码。而在 Clhoria + Claude Code + cursor 的模式下：
- 你只需要描述需求："帮我添加一个用户管理模块，包含增删改查和权限控制"
- AI 理解架构并生成代码：自动遵循项目规范，生成符合团队风格的代码
- 类型安全自动保证：编译时就能发现所有类型错误，不用等到运行时
- 文档自动同步：OpenAPI 规范，代码即文档，永不过时
技术架构：每一个选择都为开发体验权衡
🎯 技术栈选型理由
| 技术选择 | 为什么选它 | 带来的价值 |
|---|---|---|
| Hono | 语法简洁优雅，生态和性能还不错 | 129,234 req/s，轻量级但功能完整 |
| TypeScript + Zod | 运行时验证 + 编译时类型 | 100% 类型安全，拒绝 any |
| Drizzle ORM | 类型安全的 SQL，不是魔法字符串 | 数据库操作也有智能提示 |
🏗️ 架构设计：简单且实用
bash
src/
├── routes/
│ ├── public/ # 无需认证的公开接口
│ ├── client/ # 客户端接口（JWT 认证）
│ └── admin/ # 管理端接口（JWT + RBAC）
├── services/ # 复用的业务逻辑
├── db/schema/ # 数据库模型定义
└── middlewares/ # 中间件层设计原则：
- 按需抽象：简单的 CRUD 直接写在 handler，复杂逻辑才抽离 service
- 类型驱动：从数据库到 API 响应，全链路类型推导
- 声明式编程：用 Zod schema 声明数据结构，自动生成验证、类型和文档
实际开发体验：让繁琐变简单
📊 开发效率对比数据
| 开发任务 | 传统方式耗时 | Clhoria + AI 耗时 | 效率提升 |
|---|---|---|---|
| 创建完整 CRUD 模块 | 2-3 小时 | 5-10 分钟 | 15-35倍 |
| 添加字段并更新相关代码 | 30-60 分钟 | 2-3 分钟 | 10-30倍 |
| 编写单元测试 | 1-2 小时 | 5-10 分钟 | 6-24倍 |
| 更新 API 文档 | 20-30 分钟 | 0 分钟（自动生成） | ∞ |
| 实现复杂权限逻辑 | 3-4 小时 | 15-20 分钟 | 9-16倍 |
应用场景：灵活的适配所有的场景
💡 独特优势场景
- 需要快速迭代的项目：AI 辅助开发，需求变更不再痛苦
- 团队协作项目：统一的代码规范，AI 自动遵循
- 高可靠性要求：编译时类型检查 + 自动化测试
- 需要长期维护：清晰的架构，AI 能理解的代码
⚡ 框架性能对比
基于 Node22 环境的实际测试数据：
| 框架 | 请求/秒 | 相对性能 |
|---|---|---|
| Fastify | 142,695 | 100% |
| Hono (本项目) | 129,234 | 90.6% |
| Express | 51,783 | 36.3% |
| Koa | 68,591 | 48.1% |
📈 开发指标对比
| 指标 | Clhoria | 传统框架 | 提升 |
|---|---|---|---|
| 类型覆盖率 | 100% | 30-60% | 1.7-3.3倍 |
| 文档同步率 | 100% | 20-50% | 2-5倍 |
| 测试编写速度 | 5-10分钟/模块 | 60-120分钟/模块 | 6-24倍 |
| Bug 发现时机 | 编译时 | 运行时 | 提前数小时到数天 |
| 代码复用率 | 80%+ | 30-50% | 1.6-2.7倍 |
开始使用：5 分钟上手
环境要求
- Node.js >= 22
- PostgreSQL >= 17
- Redis >= 7
快速开始
bash
# 克隆项目
git clone https://github.com/zhe-qi/clhoria-template
cd clhoria-template
# 安装依赖
pnpm install
# 配置环境变量，根据要求修改url
cp .env.example .env
# 如果没有安装 postgres 17+ 和 redis 7+ 需要先安装一下
# 初始化数据库
pnpm push
# 种子，如果需要的话
pnpm seed
# 启动开发服务器
pnpm dev访问 http://localhost:9999 查看 API 文档，一切就绪！
核心功能清单
✅ 基础设施
- JWT 双令牌认证（管理端/客户端分离）
- Casbin RBAC 细粒度权限控制
- Redis 缓存 + 限流
- Pino 结构化日志
✅ 开发工具
- OpenAPI 自动文档生成
- Zod 运行时验证 + 类型推导
- 热重载开发环境
- Vitest 单元测试框架
✅ 业务功能
- 用户管理（注册/登录/权限）
- 角色管理（创建/分配/继承）
- 菜单权限（动态路由）
- 操作审计（日志记录）
- 文件上传（S3 兼容存储）
- 任务队列（BullMQ）
- 验证码系统（Cap.js）
Claude Code 深度集成：AI 原生开发体验
🤖 什么是上下文工程？
在 AI 时代，开发者的角色正在转变：
以前 ：编写每一行代码 → 现在 ：设计系统 + 描述需求 以前 ：记忆 API 细节 → 现在 ：理解业务逻辑 以前 ：手动维护文档 → 现在：代码即文档
📋 项目已配置的 AI 优化
-
完整的 CLAUDE.md 配置文件
- 项目架构说明
- 编码规范定义
- 常用命令集合
-
MCP 插件支持
- Serena：智能代码分析
- Context7：实时文档查询
-
智能提示优化
- 路由模块模板
- 服务函数规范
- 错误处理模式
💬 实际对话示例
markdown
你: 帮我添加一个文章管理功能，包含分类、标签、草稿箱
Claude: 我来帮您添加文章管理功能。根据项目规范，我会创建以下内容：
1. 数据库 Schema（文章表、分类表、标签表、关联表）
2. Admin 路由（完整 CRUD + 草稿管理）
3. Client 路由（文章列表、详情查看）
4. 相关的类型定义和验证规则
[自动生成所有代码，包含正确的权限控制、缓存策略、分页查询等]技术细节：理解才能用好
🔐 多层认证体系
typescript
// Public 路由：无需认证
app.route("/api/public", publicRoutes);
// Client 路由：JWT 认证
app.use("/api/client/*", clientAuth());
app.route("/api/client", clientRoutes);
// Admin 路由：JWT + Casbin RBAC
app.use("/api/admin/*", adminAuth());
app.use("/api/admin/*", casbinMiddleware());
app.route("/api/admin", adminRoutes);📝 类型安全的数据流
typescript
// 1. 定义 Drizzle Schema
export const articles = pgTable("articles", {
id: uuid().primaryKey(),
title: varchar({ length: 200 }).notNull(),
content: text().notNull(),
...defaultColumns
});
// 2. 自动生成 Zod Schema
export const selectArticleSchema = createSelectSchema(articles);
export const insertArticleSchema = createInsertSchema(articles);
// 3. OpenAPI 路由定义
export const create = createRoute({
method: "post",
path: "/articles",
request: {
body: {
content: { "application/json": { schema: insertArticleSchema } }
}
},
responses: {
200: jsonContent(selectArticleSchema, "创建成功")
}
});
// 4. 类型自动推导到 Handler
export const create: ArticleHandlerType<"create"> = async (c) => {
const data = c.req.valid("json"); // 类型完全安全！
// ...
};🚄 高性能设计
- 连接池管理：PostgreSQL 和 Redis 连接池优化
- 查询优化：声明式查询器，自动优化 SQL
- 缓存策略：多级缓存，热数据内存缓存
- 异步处理：BullMQ 任务队列，避免阻塞主线程
与传统方案的本质区别
❌ 传统代码生成器的问题
- 生成后失控：生成的代码很快就会被手动修改，无法重新生成
- 模板僵化：只能生成预定义的模板，复杂需求无能为力
- 风格混乱：不同时期生成的代码风格不一致
- 维护困难：没有类型约束，重构如同拆炸弹
✅ Clhoria + AI 的优势
- 持续可控：AI 理解整个项目结构，可以持续维护和更新
- 灵活适配：根据具体需求生成定制化代码
- 风格统一：严格遵循项目规范，保持代码一致性
- 安全重构：完整的类型系统，重构有编译器保护
总结：选择 Clhoria 的理由
如果你正在寻找一个：
- 🚀 开发效率提升 10 倍以上的方案
- 🛡️ 类型安全、文档完整的企业级架构
- 🤖 AI 原生、面向未来的技术栈
- 📦 开箱即用、最佳实践的项目模板
那么 Clhoria Template 就是你要找的答案。
不要让重复的 CRUD 消磨你的热情，让 AI 处理琐碎，你来创造价值。
项目地址：github.com/zhe-qi/clho...
配套前端：github.com/zhe-qi/refi...
"在 AI 时代，写代码不再是目的，解决问题才是。"