开发工作流

了解开发工作流可以帮助你更高效地开发 IAM 项目。

启动开发服务器

启动所有服务：

# 启动所有服务
pnpm run dev

# 这将启动：
# - Web 应用: http://localhost:3000
# - API 服务器: http://localhost:4000

代码结构说明

前端开发 (apps/web)

前端使用 Next.js App Router，主要目录：

src/app/: 页面路由和布局
- 使用 Next.js App Router 文件系统路由
- 支持服务器组件和客户端组件
src/components/: 可复用的 React 组件
- UI 组件（基于 shadcn/ui）
- 业务组件
- 表单组件
src/lib/: 工具函数和客户端配置
- 认证客户端配置
- 工具函数
src/utils/: tRPC 客户端配置
- tRPC React Query 集成
- 类型安全的 API 调用

后端开发 (apps/server)

后端使用 Hono 框架，主要文件：

src/index.ts: 服务器入口
- 配置路由和中间件
- 集成 tRPC 服务器
- 设置认证处理器
通过 @IAM/api 包使用 tRPC 路由
- 所有业务逻辑在共享包中
- 服务器只负责路由和中间件

类型安全开发

项目使用 TypeScript 实现端到端类型安全：

1. tRPC 类型安全

前端可以直接使用后端定义的类型：

// 后端定义
export const appRouter = router({
  getUser: publicProcedure.input(z.object({ id: z.string() })).query(({ input }) => {
    return { id: input.id, name: 'User' }
  })
})

// 前端使用 - 完全类型安全
const { data } = trpc.getUser.useQuery({ id: '123' })
// data 的类型自动推断

2. 环境变量类型

使用 Zod 验证环境变量类型：

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().min(1),
    BETTER_AUTH_SECRET: z.string().min(32)
  },
  runtimeEnv: process.env
})

3. 数据库类型

Drizzle ORM 自动生成类型：

import { db } from '@IAM/db'
import { user } from '@IAM/db/schema'

// 查询结果自动推断类型
const users = await db.select().from(user)
// users 的类型: { id: string; name: string; email: string; }[]

调试技巧

1. 查看日志

服务器使用 Hono 的 logger 中间件：

app.use(logger())

所有请求都会在控制台输出日志。

2. 数据库调试

使用 Drizzle Studio 打开数据库管理界面：

pnpm run db:studio

这将打开一个 Web 界面，可以：

查看表结构
浏览数据
执行查询

3. 类型检查

运行类型检查确保没有类型错误：

pnpm run check-types

4. 前端调试

使用 React DevTools 和 Next.js DevTools：

React DevTools: 检查组件状态
Next.js DevTools: 查看路由和性能

6. 版本记录

使用 Changesets 记录你的工作：

pnpm changeset

质量与规范

项目强制执行严格的代码规范和提交标准：

1. 代码检查与格式化

项目使用 oxlint 进行静态检查，使用 oxfmt 进行格式化：

# 自动修复并格式化所有文件
pnpm run check

2. Git 提交规范

必须遵循 Conventional Commits 规范。每次提交都会经过 Husky 和 Commitlint 校验。

3. 版本记录 (Changesets)

详见版本管理指南。

开发最佳实践

1. 代码组织

将相关功能组织在同一目录
使用共享包避免代码重复
保持组件小而专注

2. 类型安全

始终使用 TypeScript 类型
利用 tRPC 的类型推断
使用 Zod 验证输入

3. 错误处理

在 tRPC 过程中处理错误
在前端显示友好的错误消息
记录错误到日志

4. 性能优化

使用 React Query 缓存
实现代码分割
优化数据库查询