df-hono-generator 1.0.0

package/bin/create.cjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+const fs = require('node:fs')
+const path = require('node:path')
+const process = require('node:process')
+
+const [, , rawTarget] = process.argv
+const targetName = rawTarget || 'my-hono-app'
+const targetDir = path.resolve(process.cwd(), targetName)
+const packageRoot = path.resolve(__dirname, '..')
+const templateRoot = path.join(packageRoot, 'template')
+
+function copyDirectory(srcDir, destDir) {
+  fs.mkdirSync(destDir, { recursive: true })
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name)
+    const destPath = path.join(destDir, entry.name)
+
+    if (entry.isDirectory()) {
+      copyDirectory(srcPath, destPath)
+      continue
+    }
+
+    fs.copyFileSync(srcPath, destPath)
+  }
+}
+
+if (!fs.existsSync(templateRoot)) {
+  console.error(`❌ 未找到模板目录: ${templateRoot}`)
+  process.exit(1)
+}
+
+if (fs.existsSync(targetDir)) {
+  const files = fs.readdirSync(targetDir)
+  if (files.length > 0) {
+    console.error(`❌ 目标目录已存在且非空: ${targetDir}`)
+    process.exit(1)
+  }
+}
+
+// 1) 复制 template 到目标目录
+copyDirectory(templateRoot, targetDir)
+
+// 2) 修改目标 package.json
+const targetPkgPath = path.join(targetDir, 'package.json')
+if (!fs.existsSync(targetPkgPath)) {
+  console.error(`❌ 未找到模板 package.json: ${targetPkgPath}`)
+  process.exit(1)
+}
+
+const targetPkg = JSON.parse(fs.readFileSync(targetPkgPath, 'utf8'))
+targetPkg.name = targetName
+delete targetPkg.bin
+fs.writeFileSync(targetPkgPath, `${JSON.stringify(targetPkg, null, 2)}\n`, 'utf8')
+
+console.log(`\n✅ 项目已创建: ${targetDir}`)
+console.log('\n下一步:')
+console.log(`  cd ${path.relative(process.cwd(), targetDir) || '.'}`)
+console.log('  pnpm install')
+console.log('  pnpm run dev\n')

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "df-hono-generator",
+  "type": "module",
+  "version": "v1.0.0",
+  "license": "MIT",
+  "bin": { "df-hono-generator": "bin/create.cjs" },
+  "files": ["bin", "template"],
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "node --import tsx --test test/**/*.test.ts"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.19.9",
+    "@hono/zod-openapi": "^1.2.2",
+    "@scalar/hono-api-reference": "^0.9.46",
+    "ali-oss": "^6.23.0",
+    "bcryptjs": "^3.0.3",
+    "better-sqlite3": "^12.6.2",
+    "dotenv": "^17.3.1",
+    "dotenv-expand": "^12.0.3",
+    "drizzle-orm": "^0.45.1",
+    "drizzle-seed": "^0.3.1",
+    "hono": "^4.12.3",
+    "hono-pino": "^0.10.3",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "redis": "^5.11.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^7.6.1",
+    "@types/ali-oss": "^6.23.3",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^20.11.17",
+    "drizzle-kit": "^0.31.9",
+    "eslint": "^10.0.2",
+    "eslint-plugin-format": "^2.0.1",
+    "tsx": "^4.7.1",
+    "typescript": "^5.8.3"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3"
+    ]
+  }
+}

package/template/.env.example

@@ -0,0 +1,25 @@
+# 环境变量
+# 环境变量 NODE_ENV 可选值：development, production
+NODE_ENV=development
+# 端口
+PORT=3000
+
+#  OSS 配置
+OSS_ACCESS_KEY_ID=你自己的阿里云的 ACCESS_KEY_ID
+OSS_ACCESS_KEY_SECRET=你自己的阿里云的 OSS_ACCESS_KEY_SECRET
+OSS_BUCKET=阿里云 OSS 的 Bucket 名称
+OSS_REGION=阿里云 OSS Bucket 所在地域名称
+OSS_BASE_URL=阿里云 OSS Bucket 域名
+
+# 数据库配置
+# 本地 SQLite 数据库文件路径（也可以像 mysql 一样使用远程数据库）
+DB_FILE_URL=./src/db/dev.db
+
+# Redis 配置
+REDIS_SERVER=redis://default:123456@localhost:6379
+
+# JWT 配置
+JWT_ADMIN_SECRET=abcdefghijklmnopqrstuvwxyz
+JWT_ADMIN_EXPIRES_IN_SECONDS=86400
+JWT_CLIENT_SECRET=zyxwvutsrqponmlkjihgfedcba
+JWT_CLIENT_EXPIRES_IN_SECONDS=86400

package/template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 South Sound
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/template/README.md

@@ -0,0 +1,327 @@
+# South Sound Server
+
+基于 `Hono + TypeScript + Zod OpenAPI` 的后端服务模板。
+
+这份文档定位为长期复用的项目手册，包含：
+
+- 快速启动
+- 环境变量规范
+- 目录与命名约定
+- 路由与返回体规范
+- 错误码规范
+- 测试与部署流程
+
+## 1. 快速开始
+
+### 1.1 环境要求
+
+- Node.js `>= 20`
+- pnpm `>= 8`
+
+### 1.2 安装依赖
+
+```bash
+pnpm install
+```
+
+### 1.3 配置环境变量
+
+```bash
+cp .env.example .env
+```
+
+按下文「环境变量说明」补齐配置。
+
+### 1.4 本地开发
+
+```bash
+pnpm run dev
+```
+
+默认地址：`http://localhost:3000`
+
+### 1.5 API 文档
+
+- OpenAPI JSON: `GET /doc`
+- Scalar UI: `GET /scalar`
+
+## 2. 环境变量说明
+
+环境变量由 [`src/env.ts`](src/env.ts) 使用 Zod 在启动时校验，不满足要求会直接退出进程。
+
+| 变量名                          | 必填 | 默认值                               | 说明                               |
+| ------------------------------- | ---- | ------------------------------------ | ---------------------------------- |
+| `NODE_ENV`                      | 否   | `development`                        | 运行环境                           |
+| `PORT`                          | 否   | `3000`                               | 服务端口                           |
+| `OSS_ACCESS_KEY_ID`             | 是   | -                                    | 阿里云 OSS AccessKey ID            |
+| `OSS_ACCESS_KEY_SECRET`         | 是   | -                                    | 阿里云 OSS AccessKey Secret        |
+| `OSS_BUCKET`                    | 是   | -                                    | OSS Bucket 名称                    |
+| `OSS_REGION`                    | 是   | -                                    | OSS Region，例如 `oss-cn-hangzhou` |
+| `OSS_BASE_URL`                  | 是   | -                                    | OSS 对外访问基础地址               |
+| `DB_FILE_URL`                   | 否   | `./src/db/dev.db`                    | SQLite 文件路径                    |
+| `REDIS_SERVER`                  | 否   | `redis://user:123456@localhost:6379` | Redis 连接串                       |
+| `JWT_ADMIN_SECRET`              | 是   | -                                    | 管理端 JWT 密钥                    |
+| `JWT_ADMIN_EXPIRES_IN_SECONDS`  | 否   | `86400`                              | 管理端 JWT 过期秒数（最小 60）     |
+| `JWT_CLIENT_SECRET`             | 是   | -                                    | 客户端 JWT 密钥                    |
+| `JWT_CLIENT_EXPIRES_IN_SECONDS` | 否   | `86400`                              | 客户端 JWT 过期秒数（最小 60）     |
+
+说明：
+
+- “必填”以 [`src/env.ts`](src/env.ts) 的 Zod schema 是否提供默认值为准。
+- 即使有默认值，生产环境也建议显式配置，避免不同环境行为不一致。
+
+示例：
+
+```env
+# 基本信息
+NODE_ENV=development
+PORT=3000
+
+# OSS 配置
+OSS_ACCESS_KEY_ID=your_key_id
+OSS_ACCESS_KEY_SECRET=your_key_secret
+OSS_BUCKET=your_bucket
+OSS_REGION=oss-cn-hangzhou
+OSS_BASE_URL=https://your-bucket.oss-cn-hangzhou.aliyuncs.com
+
+# 数据库配置
+DB_FILE_URL=./src/db/dev.db
+
+# Redis 配置
+REDIS_SERVER=redis://user:123456@localhost:6379
+
+# JWT 配置
+JWT_ADMIN_SECRET=abcdefghijklmnopqrstuvwxyz
+JWT_ADMIN_EXPIRES_IN_SECONDS=86400
+JWT_CLIENT_SECRET=zyxwvutsrqponmlkjihgfedcba
+JWT_CLIENT_EXPIRES_IN_SECONDS=86400
+```
+
+## 3. 常用命令
+
+```bash
+pnpm run dev      # 开发模式（tsx watch）
+pnpm run build    # TypeScript 构建到 dist
+pnpm run start    # 运行构建产物
+pnpm run lint     # 代码检查
+pnpm run lint:fix # 自动修复格式与部分 lint 问题
+pnpm run test     # 运行测试（node:test + tsx）
+```
+
+## 4. 目录约定
+
+```text
+src/
+  app.ts                    # 应用入口，统一挂载业务路由
+  index.ts                  # 启动 HTTP 服务
+  env.ts                    # 环境变量加载与校验
+  lib/                      # 基础库（app factory、响应封装、状态码等）
+  middleware/               # 中间件
+  routes/
+    <module>/
+      <module>.routes.ts    # 路由声明（createRoute + schema）
+      <module>.handler.ts   # 业务处理逻辑
+      <module>.index.ts     # 模块路由聚合（router.openapi）
+
+ test/
+   *.test.ts                # 集成/接口测试
+```
+
+新增业务模块时，建议沿用三件套：
+
+- `xxx.routes.ts`
+- `xxx.handler.ts`
+- `xxx.index.ts`
+
+并在 [`src/app.ts`](src/app.ts) 中统一注册：
+
+```ts
+app.route('/prefix', xxxRouter)
+```
+
+## 5. 路由规范
+
+### 5.1 设计原则
+
+- 使用 `@hono/zod-openapi` 的 `createRoute` 声明路由。
+- 每个接口必须声明：`path`、`method`、`tags`、`responses`。
+- 有请求体时必须提供 Zod schema（便于自动校验与文档生成）。
+
+### 5.2 文件职责
+
+- `*.routes.ts`：只做协议层定义（请求/响应 schema）。
+- `*.handler.ts`：只做业务逻辑与调用外部服务。
+- `*.index.ts`：路由与 handler 绑定。
+
+### 5.3 命名建议
+
+- 路由对象名使用业务语义，例如 `list`, `create`, `detail`, `update`, `remove`。
+- handler 与 route 对象同名，减少映射负担。
+
+### 5.4 URL 约定
+
+- 模块级前缀在 `app.ts` 中统一挂载。
+- 具体接口 path 在 `*.routes.ts` 中定义。
+- 建议采用资源化命名，避免动词堆叠。
+
+## 6. 响应与错误码规范
+
+### 6.1 成功响应
+
+统一通过 [`src/lib/response.ts`](src/lib/response.ts) 的 `ok()` 返回：
+
+```json
+{
+  "success": true,
+  "code": 0,
+  "message": "操作成功",
+  "data": {}
+}
+```
+
+约定：
+
+- `success = true`
+- `code = 0`（业务成功码）
+- HTTP 状态码通常为 `200`
+
+### 6.2 失败响应
+
+统一通过 `fail()` 返回：
+
+```json
+{
+  "success": false,
+  "code": 400,
+  "message": "参数校验失败",
+  "error": {}
+}
+```
+
+约定：
+
+- `success = false`
+- `code` 与 HTTP 状态码/错误标识一致
+- `message` 为可读错误信息
+- `error` 仅在需要排障时提供结构化详情
+
+### 6.3 当前全局错误处理
+
+在 [`src/lib/create-app.ts`](src/lib/create-app.ts) 中已内置：
+
+- 参数校验失败：`400 BAD_REQUEST`
+- 路由不存在：`404 NOT_FOUND`
+- 未捕获异常：`500 INTERNAL_SERVER_ERROR`
+
+建议新增业务错误时使用：
+
+- `400` 参数错误
+- `401` 未认证
+- `403` 无权限
+- `404` 资源不存在
+- `409` 资源冲突
+- `422` 语义校验失败
+- `500` 服务内部错误
+
+## 7. 测试规范
+
+项目当前使用 `node:test` + `tsx`。
+
+### 7.1 存放约定
+
+- 测试文件放在根目录 `test/`
+- 文件命名：`*.test.ts`
+
+### 7.2 运行测试
+
+```bash
+pnpm run test
+```
+
+### 7.3 测试目标建议
+
+- 每个路由至少覆盖：
+  - 1 个成功用例
+  - 1 个参数校验失败用例
+  - 关键异常路径（如外部服务失败）
+- 断言内容至少包括：
+  - HTTP 状态码
+  - `success/code/message/data(error)` 结构
+
+## 8. 部署步骤（通用）
+
+以下流程适用于 Linux 服务器（systemd/pm2 均可复用）。
+
+### 8.1 拉取代码并安装依赖
+
+```bash
+pnpm install --frozen-lockfile
+```
+
+### 8.2 配置生产环境变量
+
+```bash
+cp .env.example .env
+# 编辑 .env，填入生产值
+```
+
+建议至少设置：
+
+- `NODE_ENV=production`
+- `PORT=<生产端口>`
+- OSS 相关全部变量
+- `DB_FILE_URL`
+- `REDIS_SERVER`
+- JWT 相关全部变量（`JWT_ADMIN_SECRET`、`JWT_CLIENT_SECRET` 等）
+
+### 8.3 构建
+
+```bash
+pnpm run build
+```
+
+### 8.4 启动
+
+```bash
+pnpm run start
+```
+
+### 8.5 进程守护（推荐）
+
+可用 `pm2` 示例：
+
+```bash
+pm2 start dist/src/index.js --name south-sound-server
+pm2 save
+pm2 startup
+```
+
+### 8.6 反向代理（可选）
+
+建议在 Nginx/Caddy 前置：
+
+- 统一 TLS
+- 统一域名与路由
+- 限流与日志聚合
+
+## 9. 新增模块 Checklist
+
+- 新建 `src/routes/<module>/` 三件套文件
+- 在 `*.routes.ts` 完成 schema 与响应声明
+- 在 `*.handler.ts` 实现业务逻辑
+- 在 `src/app.ts` 注册路由前缀
+- 为核心接口补充 `test/*.test.ts`
+- 本地通过 `pnpm run lint && pnpm run test`
+
+## 10. 已知注意事项
+
+- 环境变量缺失会在启动时直接退出（预期行为）。
+- 测试中如果导入 `app` 依赖 `env`，需要在测试前准备必要的 `process.env`。
+- 建议保持返回结构稳定，避免前端联调频繁改动。
+
+## 11. License
+
+This project is licensed under the [MIT License](./LICENSE).
+
+You are free to use, modify, distribute, and use this project commercially,
+as long as the original copyright and license notice are retained.

package/template/docker-compose.yml

@@ -0,0 +1,8 @@
+services:
+  redis:
+    image: redis:7.4
+    command: [redis-server, --requirepass, '${REDIS_PASSWORD}']
+    environment:
+      - REDIS_PASSWORD=123456
+    ports:
+      - '6379:6379'

package/template/drizzle.config.ts

@@ -0,0 +1,10 @@
+import process from 'node:process'
+
+export default {
+  schema: './src/db/schema.ts', // 表定义
+  out: './src/db/migrations', // 迁移文件输出目录
+  dialect: 'sqlite',
+  dbCredentials: {
+    url: process.env.DB_FILE_URL ?? 'file:./dev.db', // 数据库文件路径
+  },
+}

package/template/eslint.config.js

@@ -0,0 +1,9 @@
+import antfu from '@antfu/eslint-config'
+
+export default antfu({
+  formatters: true,
+  rules: {
+    'test/no-import-node-test': 'off',
+    'no-console': ['error', { allow: ['warn', 'error', 'log'] }],
+  },
+})

package/template/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "df-hono-generator",
+  "type": "module",
+  "version": "v1.0.0",
+  "license": "MIT",
+  "bin": { "df-hono-generator": "bin/create.cjs" },
+  "files": ["bin", "template"],
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "node --import tsx --test test/**/*.test.ts"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.19.9",
+    "@hono/zod-openapi": "^1.2.2",
+    "@scalar/hono-api-reference": "^0.9.46",
+    "ali-oss": "^6.23.0",
+    "bcryptjs": "^3.0.3",
+    "better-sqlite3": "^12.6.2",
+    "dotenv": "^17.3.1",
+    "dotenv-expand": "^12.0.3",
+    "drizzle-orm": "^0.45.1",
+    "drizzle-seed": "^0.3.1",
+    "hono": "^4.12.3",
+    "hono-pino": "^0.10.3",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "redis": "^5.11.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^7.6.1",
+    "@types/ali-oss": "^6.23.3",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^20.11.17",
+    "drizzle-kit": "^0.31.9",
+    "eslint": "^10.0.2",
+    "eslint-plugin-format": "^2.0.1",
+    "tsx": "^4.7.1",
+    "typescript": "^5.8.3"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3"
+    ]
+  }
+}

package/template/src/app.ts

@@ -0,0 +1,26 @@
+import { configureOpenAPI } from '@/lib/configure-open-api.js'
+import createApp from '@/lib/create-app.js'
+import adminAuth from '@/routes/auth/auth.index.js'
+import alioss from '@/routes/oss/alioss.index.js'
+import { requireAdminAuth, requireEitherAuth } from './middleware/auth.js'
+
+const app = createApp()
+
+configureOpenAPI(app)
+
+// 启用中间件
+app.use('/admin/*', requireAdminAuth())
+app.use('/oss/*', requireEitherAuth())
+
+// 定义路由数组
+const routes = [
+  { path: '/oss', router: alioss },
+  { path: '/admin/auth', router: adminAuth },
+]
+
+// 注册所有路由
+routes.forEach(({ path, router }) => {
+  app.route(path, router)
+})
+
+export default app

package/template/src/db/index.ts

@@ -0,0 +1,8 @@
+import Database from 'better-sqlite3'
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import env from '@/env.js'
+
+const sqlite = new Database(env.DB_FILE_URL)
+const db = drizzle({ client: sqlite })
+
+export default db

package/template/src/db/migrations/0000_outgoing_gamora.sql

@@ -0,0 +1,6 @@
+CREATE TABLE `test` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`username` text NOT NULL,
+	`gender` integer DEFAULT 0 NOT NULL,
+	`created_at` integer NOT NULL
+);