艾特我

博客

  • 我如何从零构建一个生产级 React SSR 框架

    前言

    在 React 生态系统中，Next.js 作为 SSR 框架的代表，以其开箱即用的体验和强大的功能深受开发者喜爱。但对于想要完全掌控构建流程、深度定制部署方案、或者只是想学习 SSR 底层原理的开发者来说，Next.js 的"黑盒"特性反而成为了一种限制。

    最近，我花了几个月时间，从零开始构建了一个轻量级但功能完整的 React SSR 框架——NSBP (Node React SSR by Webpack)。今天，我想分享一下这个项目的开发历程、技术选型、核心特性以及从中获得的实战经验。

    在线演示: https://nsbp.erishen.cn/
    GitHub: https://github.com/erishen/nsbp

    一、为什么选择自建而不是 Next.js？

    1.1 完全掌控构建流程

    Next.js 的强大来自于它的自动化，但这也意味着你失去了一些控制权：

    # Next.js 的构建过程（黑盒）
next build
# → 自动路由
# → 自动代码分割
# → 自动图片优化
# → ... 你看不到的几百个步骤

    而在 NSBP 中，你可以精确控制每一个构建步骤：

    // config/webpack.base.js
module.exports = {
  entry: {
    client: './src/client/index.tsx',
    server: './src/server/index.ts'
  },
  plugins: [
    new MiniCssExtractPlugin(),
    new TerserPlugin(),
    // ... 你可以添加任何 Webpack 插件
  ]
}

    1.2 深度定制部署方案

    Next.js 自带的 Vercel 部署确实方便，但如果你想：

    • 在自己的 Linux 服务器上部署
    • 使用 Docker Compose 编排多个服务
    • 配置反向代理和负载均衡
    • 实现特定的安全策略

    那么自己掌控 Express 服务器会更有优势。

    1.3 学习 SSR 的底层原理

    通过手写 SSR 渲染逻辑，你将深入理解：

    // SSR 渲染流程
const sheet = new ServerStyleSheet()
const jsx = sheet.collectStyles(
  <Provider store={store}>
    <StaticRouter location={reqPath}>
      <Routes>{/* ... */}</Routes>
    </StaticRouter>
  </Provider>
)
const content = renderToString(jsx)
const styleTags = sheet.getStyleTags()

    这些知识对你在任何 React SSR 项目中都非常有价值。

    二、技术选型与架构设计

    2.1 核心技术栈

    类别 技术选型 版本 理由
    React React 19.2.3 最新版本，并发特性，更好的类型支持
    状态管理 Redux Toolkit 简化 Redux 开发，内置 Thunk 支持
    路由 React Router DOM 7.12.0 稳定的客户端路由
    代码分割 @loadable/component 5.15.0，成熟的代码分割方案
    构建工具 Webpack 5.96.0 模块化、可扩展、生态丰富
    服务端 Express 5.2.1 轻量级、中间件生态完善
    样式方案 Styled-components + Sass/Less 多种选择，灵活切换
    TypeScript 5.x 类型安全，开发体验优秀

    2.2 SSR 渲染架构

    ┌─────────────────────────────────────────┐
│         HTTP 请求                         │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│       Express 中间件层                │
│  ┌──────────────┬──────────────┐       │
│  │ Helmet (安全) │ Rate Limit  │       │
│  └──────────────┴──────────────┘       │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│       SSR 渲染层                     │
│  1. 创建 Redux Store                 │
│  2. 预取路由数据 (loadData)         │
│  3. renderToString 渲染 HTML        │
│  4. 提取 Styled-components 样式    │
│  5. 序列化状态到 window.context      │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│       返回 HTML + 初始状态            │
│  <html>                            │
│    <head>                          │
│      ${styleTags}                    │
│    </head>                          │
│    <body>                          │
│      <div id="root">${content}</div>   │
│      <script>                        │
│        window.context = { state: ... } │
│      </script>                        │
│    </body>                          │
│  </html>                            │
└─────────────────────────────────────────┘

    2.3 客户端 Hydration 流程

    // src/client/index.tsx
const App = () => {
  const store = useMemo(() => {
    // 读取服务端传递的状态
    if (isSEO() && window?.context?.state) {
      return getStore(window.context.state)
    }
    return getStore()
  }, [])

  return (
    <Provider store={store}>
      <BrowserRouter>
        <Routes>{/* ... */}</Routes>
      </BrowserRouter>
    </Provider>
  )
}

// 等待代码分割组件加载完成
loadableReady(() => {
  hydrateRoot(document.getElementById('root')!, <App />)
})

    三、核心特性详解

    3.1 三种渲染模式（灵活切换）

    NSBP 支持通过 URL 参数控制渲染模式：

    模式 URL 场景
    SSR（默认） / 或 /?nsbp=1 SEO 优化、首屏加载快
    CSR（纯客户端） /?nsbp=0 调试、开发体验
    SSR 回退 /?nsbp=1&from=link 内部链接，允许客户端更新

    实现逻辑：

    // src/utils/index.ts
export const isSEO = () => {
  if (typeof window !== 'undefined') {
    const nsbp = getLocationParams('nsbp')
    if (nsbp !== '') {
      return parseInt(nsbp, 10)
    }
    return 1  // 默认 SSR
  }
  return 1
}

    3.2 智能 SSR 数据预取

    服务端预取数据，避免客户端二次请求：

    // src/Routers.tsx
export default [
  {
    path: '/',
    element: <Home />,
    loadData: homeLoadData,  // ← SSR 时预取数据
    key: 'home'
  }
]

// src/services/home.ts
export const loadData = (resolve: any, query: any) => {
  return async (dispatch: any) => {
    try {
      const response = await fetch('/getPhotoMenu')
      const data = await response.json()

      // Redux Thunk action
      dispatch({
        type: FETCH_PHOTO_MENU_SUCCESS,
        payload: data.data
      })

      resolve()
    } catch (error) {
      console.error('Data loading error:', error)
      resolve()
    }
  }
}

    效果对比：

    传统 CSR 方式：
  1. 客户端请求页面 → 返回空 HTML
  2. 加载 JS bundle
  3. 执行 JS
  4. 发起 API 请求
  5. 渲染内容
  ⏱️ 总耗时: ~2-3 秒

NSBP SSR 方式：
  1. 服务端预取数据
  2. 渲染完整 HTML
  3. 返回给客户端
  4. 客户端直接 hydrate
  ⏱️ 总耗时: ~0.5-1 秒

    3.3 代码分割与懒加载

    使用 @loadable/component 实现路由级别的代码分割：

    import loadable from '@loadable/component'

const Home = loadable(() => import('@containers/Home'), {
  fallback: <Loading />
})

const Photo = loadable(() => import('@containers/Photo'), {
  fallback: <Loading />
})

    Webpack 配置：

    // config/webpack.client.js
const { ChunkExtractor } = require('@loadable/webpack-plugin')

module.exports = merge(baseConfig, {
  mode: 'production',
  plugins: [
    new ChunkExtractor({
      statsFile: path.resolve(__dirname, '../public/loadable-stats.json')
    })
  ]
})

    效果：

    首次加载：
  - 主 bundle: ~200KB
  - 只加载首页代码

访问 /photo 页面：
  - 按需加载 Photo 组件
  - 不加载 Login 组件

    3.4 多层安全防护体系

    Helmet 安全头部

    // src/server/index.ts
app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'", "'unsafe-inline'", "'unsafe-eval'"],
      styleSrc: ["'self'", "'unsafe-inline'"],
      imgSrc: ["'self'", 'data:', 'https:'],
      connectSrc: ["'self'", 'https:'],
      fontSrc: ["'self'", 'data:'],
      objectSrc: ["'none'"],
      mediaSrc: ["'self'"],
      frameSrc: ["'none'"]
    }
  },
  crossOriginEmbedderPolicy: false,
  crossOriginOpenerPolicy: false
}))

    安全效果：

    攻击类型 防护措施
    XSS 攻击 CSP script-src 策略
    点击劫持 X-Frame-Options: SAMEORIGIN
    MIME 嗅探 X-Content-Type-Options: nosniff
    不安全的 HTTPS Strict-Transport-Security

    速率限制

    if (process.env.ENABLE_RATE_LIMIT === '1') {
  const limiter = rateLimit({
    windowMs: 15 * 60 * 1000,  // 15 分钟
    max: 100,                     // 最多 100 次请求
    message: 'Too many requests from this IP'
  })
  app.use('/api', limiter)
}

    3.5 Docker 一键部署

    生产环境 (docker-compose.yml)：

    services:
  app:
    build:
      context: .
      dockerfile: docker/Dockerfile
    container_name: nsbp-app
    ports:
      - "8081:3001"
    environment:
      - NODE_ENV=production
      - ENABLE_RATE_LIMIT=1
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3001', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"]
      interval: 30s
      timeout: 3s
      retries: 3

    开发环境 (docker-compose.dev.yml)：

    services:
  app:
    build:
      context: .
      dockerfile: docker/Dockerfile.dev
    container_name: nsbp-app-dev
    ports:
      - "3001:3001"
      - "9229:9229"  # Node.js debug port
    volumes:
      # 代码挂载（热重载）
      - ./src:/app/src
      - ./public:/app/public
      - ./config:/app/config
    command: ["dumb-init", "--", "pnpm", "run", "dev"]

    一键启动：

    # 生产环境
make prod
# 或
docker-compose up -d

# 开发环境
make dev
# 或
docker-compose -f docker-compose.dev.yml up --build

    四、开发体验优化

    4.1 完整的代码质量工具链

    // package.json scripts
{
  "scripts": {
    "lint": "eslint src --ext .ts,.tsx,.js,.jsx",
    "lint:fix": "eslint src --ext .ts,.tsx,.js,.jsx --fix",
    "format": "prettier --write **/*.{js,css,less,scss,ts,tsx}"
  }
}

    Git Hooks (Husky + lint-staged)：

    // .husky/pre-commit
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

lint-staged --partial-staged

    效果：

    $ git add .
$ git commit -m "feat: add new component"
✔ Pre-commit checks
  → ESLint auto-fixed 3 files
  → Prettier formatted 5 files
[master 8a3f9d] feat: add new component

    4.2 CLI 工具快速创建项目

    # 安装 CLI
npm install -g nsbp-cli

# 创建新项目
npx nsbp-cli create my-app

# 项目结构
my-app/
├── src/
│   ├── client/
│   ├── server/
│   ├── containers/
│   ├── component/
│   ├── store/
│   └── utils/
├── docker/
│   ├── Dockerfile
│   ├── Dockerfile.dev
│   ├── docker-compose.yml
│   └── docker-compose.dev.yml
├── config/
│   ├── webpack.base.js
│   ├── webpack.client.js
│   └── webpack.server.js
├── .env.example
├── Makefile
└── README.md

    4.3 Make 命令简化操作

    # 查看所有命令
make help

Available targets:
  help            Show this help message
  build           Build Docker images for production
  dev             Start development environment
  prod            Start production environment
  down            Stop and remove containers
  logs            View logs
  restart         Restart production containers
  rebuild         Rebuild and restart containers
  shell           Open shell in container

    五、性能优化实践

    5.1 Tree Shaking

    // config/webpack.base.js
module.exports = {
  optimization: {
    usedExports: true,  // 只导出使用的导出
    sideEffects: false,  // 没有副作用
  }
}

    5.2 代码压缩与混淆

    // config/webpack.client.js (production)
const TerserPlugin = require('terser-webpack-plugin')

module.exports = {
  optimization: {
    minimize: true,
    minimizer: [
      new TerserPlugin({
        parallel: true,  // 多进程压缩
        terserOptions: {
          compress: {
            drop_console: true,  // 移除 console.log
            pure_funcs: ['console.log', 'console.info']
          }
        }
      })
    ]
  }
}

    5.3 静态资源缓存优化

    // src/server/index.ts
app.use(express.static('public', {
  dotfiles: 'ignore',
  setHeaders: (res, filePath) => {
    // 缓存 1 年
    if (filePath.match(/\.(js|css|png|jpg|jpeg|gif|svg|ico)$/)) {
      res.setHeader('Cache-Control', 'public, max-age=31536000, immutable')
    }
  }
}))

    5.4 图片尺寸探测

    // 使用 probe-image-size 在 SSR 阶段获取图片尺寸
import { getPhotoWH } from '@server/photo'

// 客户端直接使用，避免二次请求
const [width, height, filename] = photos[0]

    六、适用场景分析

    ✅ 适合使用 NSBP 的场景

    1. 个人项目和快速原型

      • 需要快速搭建 SSR 应用
      • 想要学习 SSR 原理
      • 对构建流程有特殊需求

    2. 教育和学习目的

      • 深入理解 React SSR
      • 学习 Webpack 配置
      • 掌握 Redux 状态管理

    3. 需要高度定制的项目

      • 自定义构建流程
      • 特殊的安全策略
      • 自定义部署方案

    4. 低资源环境部署

      • 小型 VPS 服务器
      • 需要优化镜像大小
      • 精确控制资源占用

    ❌ 不适合使用 NSBP 的场景

    1. 企业级大型应用

      • Next.js 的自动优化能节省大量时间
      • 需要 Image Optimization、API Routes 等高级功能
      • 团队规模大，需要统一的开发规范

    2. 快速迭代的项目

      • 开发速度 > 定制能力
      • 不想深入理解底层原理

    3. 需要 AI/ML 功能

      • Next.js 的 AI SDK 集成
      • Vercel AI Platform 支持

    七、遇到的问题与解决方案

    7.1 React 19 Hydration 错误 #418

    问题：在 HTTPS 环境下，Home 组件报错：

    Minified React error #418

    原因：组件中使用了 dangerouslySetInnerHTML 的 <script> 标签，导致服务端和客户端 HTML 不匹配。

    // ❌ 错误写法
<script
  dangerouslySetInnerHTML={{
    __html: `setTimeout(() => { ... }, 800)`
  }}
/>

    解决方案：将脚本逻辑移到 useEffect 中。

    // ✅ 正确写法
useEffect(() => {
  const timer = setTimeout(() => {
    // 客户端执行
  }, 300)
  return () => clearTimeout(timer)
}, [])

    7.2 Docker 端口配置问题

    问题：.env 文件在根目录，docker-compose.yml 在 docker/ 目录，导致环境变量无法读取。

    # 目录结构
nsbp/
├── .env              # 环境变量
└── docker/
    └── docker-compose.yml  # 配置文件

    解决方案：

    1. 将 docker-compose.yml 移到根目录
    2. 更新 Makefile 移除 docker/ 路径前缀
    3. 更新 CLI 模板保持一致
    // docker-compose.yml (现在在根目录）
services:
  app:
    build:
      context: .  // ← 直接使用根目录
      dockerfile: docker/Dockerfile

    7.3 Webpack Dev Server 热重载失效

    问题：修改样式文件后，页面没有自动刷新。

    原因：Browser Sync 配置不正确。

    解决方案：正确配置 Browser Sync Webpack Plugin。

    const BrowserSyncPlugin = require('browser-sync-webpack-plugin')

module.exports = {
  plugins: [
    new BrowserSyncPlugin({
      host: 'localhost',
      port: 3000,
      proxy: {
        target: 'http://localhost:3001',
        ws: true
      }
    })
  ]
}

    八、未来规划与改进方向

    8.1 技术升级

    • 升级到 React Server Components（React 19 新特性）
    • 集成 tRPC 替代 Axios（类型安全的 API）
    • 使用 Vitest 替代 Jest（更快的测试框架）
    • 添加 Storybook 组件文档

    8.2 性能优化

    • 实现 Service Worker 缓存
    • 添加 CDN 支持静态资源
    • 图片懒加载 + WebP 格式转换
    • 实现 ISR (Incremental Static Regeneration)

    8.3 开发体验

    • 添加 TypeScript 路径自动导入
    • 实现代码生成工具（CRUD 模板）
    • 集成 e2e 测试（Playwright）
    • 添加性能监控和分析

    九、总结

    收获与经验

    技术层面：

    • 深入理解了 React SSR 的工作原理
    • 掌握了 Webpack 的复杂配置
    • 熟练使用 Redux Toolkit 状态管理
    • 学会了 Docker 容器化部署

    工程层面：

    • 建立了完整的代码质量工具链
    • 实现了自动化部署流程
    • 掌握了 CLI 工具开发
    • 理解了软件架构设计原则

    对比 Next.js

    特性 NSBP Next.js
    学习曲线 陡峭（需要 Webpack 知识） 平缓（开箱即用）
    定制能力 完全可控 有限（受框架限制）
    部署灵活性 高（可自定义任何方案） 中（优先 Vercel）
    开发体验 需要配置 优秀（零配置）
    性能优化 手动控制 自动优化
    适用场景 学习、个人项目、高度定制 企业应用、快速开发

    给新手的建议

    1. 先学 Next.js：理解 SSR 的基本概念和最佳实践
    2. 再学 Webpack：掌握构建工具的底层原理
    3. 尝试 NSBP：理解一个完整的 SSR 框架是如何工作的
    4. 动手实践：自己构建一些小项目，深入理解每个环节

    十、快速开始

    # 1. 安装依赖
pnpm install

# 2. 配置环境
cp .env.example .env

# 3. 启动开发
pnpm run dev

# 4. 访问应用
open http://localhost:3001

# 5. Docker 部署
make prod

    结语

    构建 NSBP 的过程是一次非常有价值的学习经历。虽然最终产品可能不会成为 Next.js 的替代品，但通过这个项目，我：

    • 深入理解了现代前端工程化的每个环节
    • 掌握了从零构建一个完整应用的能力
    • 培养了解决复杂问题的思维模式

    技术框架的选择没有绝对的对错，只有适不适合。Next.js 适合快速开发和大多数场景，但如果你想要完全掌控、深入学习、或者有特殊需求，那么从零构建也是一种选择。

    希望这篇文章能对正在学习 React SSR 的你有所帮助！

    项目链接：

    相关文章：

    • [如何从零开始构建一个 React SSR 应用（待写）]
    • [Webpack 5 最佳实践指南（待写）]
    • [TypeScript + Redux Toolkit 实战（待写）]

    本文首发于 Erishen 的技术博客

  • 构建现代化的组件库：shadcn + Bun 带来的前端开发革命

    这篇文章分享了我如何基于 shadcn/ui 和 Bun 构建了一个自定义组件注册表，以及这个过程给我带来的关于前端开发效率的深度思考。

    前言：重新思考组件获取方式

    最近在重构公司前端项目时，我遇到了一个很有意思的问题：为什么我们总是在 npm install 上浪费这么多时间？

    这个问题让我开始思考：传统的依赖安装模式是否真的是最优解？直到我接触到了 shadcn 的理念和 Bun 的性能，才意识到前端开发工具链还有如此大的优化空间。

    项目背景：shadcn-registry 概述

    shadcn-registry 是我基于 shadcn/ui 理念构建的一个自定义组件注册表项目。这个项目的核心价值不在于组件本身，而在于它代表的一种新的开发范式。

    核心理念：

    • 🎨 组件复制而非安装：copy instead of install
    • 📦 注册表模式：建立自己的组件分发体系
    • ⚡ 极致性能：使用 Bun 重新定义开发体验
    • 🔧 完全可控：源代码级别的定制能力

    技术栈：

    - 框架：Next.js 14 (App Router)
- UI 库：React 18 + shadcn/ui + Radix UI
- 样式：Tailwind CSS 4.0、SCSS、styled-components
- 表单：React Hook Form + Zod
- 文档：Storybook 9
- 语言：TypeScript 5.5
- 包管理器：Bun 1.3+

    为什么选择 Bun：一个性能极客的思考

    开发效率的瓶颈

    作为前端开发者，我们都经历过这样的场景：

    # 项目初始化
npm install                    # 等待 30-60 秒
npm run dev                    # 等待 8-10 秒启动
npm install @tanstack/react-table   # 又等待 20-30 秒
npm run build                  # 等待 2-3 分钟构建

    这些等待时间看似微不足道，但累计起来却构成了巨大的效率损耗。

    Bun 的性能革命

    当我第一次使用 Bun 时，它的表现让我震惊：

    # 在同一个 Next.js 项目上的测试结果

# 🐌 npm (基线)
time npm install
# real    0m45.231s

# ⚡ pnpm 
time pnpm install
# real    0m12.456s

# 🚀 Bun
time bun install
# real    0m2.134s   # 比 npm 快 21 倍！

    这种速度差异不是简单的数字对比，而是开发体验的根本性改变。

    Bun 的核心技术优势：

    1. 并行下载算法

    • 同时下载多个包，充分利用网络带宽
    • 智能重试机制，处理网络异常

    2. 智能缓存系统

    • 本地缓存已下载的包，避免重复下载
    • 跨项目共享缓存，最大化资源利用

    3. 原生性能

    • 使用 Zig 语言编写，无 Node.js 运行时开销
    • 内置 JavaScript 引擎，解析速度更快

    4. 开发工具集成

    • 内置 ESBuild，打包速度提升 2-3 倍
    • 内置测试运行器，无需 Jest 配置
    • 原生 TypeScript 支持，无需额外编译步骤

    对比优势

    特性Bunnpmpnpm
    安装速度🚀 极快🐌 慢⚡ 快
    磁盘空间💾 节省📦 大💾 节省
    启动速度⚡ 7x faster🐌 baseline⚡ 3x faster
    内存占用💡 低📈 高💡 中等
    Node 兼容性✅ 99%+✅ 100%✅ 100%

    shadcn 的理念革新：从安装到复制

    传统依赖管理的痛点

    传统的 npm 包管理方式存在几个根本性问题：

    1. 依赖地狱

    // 一个简单的项目可能需要这么多依赖
{
  "dependencies": {
    "@tanstack/react-table": "^8.10.7",
    "@headlessui/react": "^1.7.17",
    "@heroicons/react": "^2.0.18",
    "react-hook-form": "^7.47.0",
    "@hookform/resolvers": "^3.3.2",
    "zod": "^3.22.4",
    "clsx": "^2.0.0",
    "tailwind-merge": "^1.14.0",
    "date-fns": "^2.30.0",
    "lodash": "^4.17.21"
    // ... 总共 30+ 个包
  }
}

    2. 版本冲突

    npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! Found: react@18.2.0
npm ERR! Could not resolve dependency: react-dom@17.0.2
npm ERR! peer react@"^16.8.0 || ^17.0.0-rc.1" from react-dom@17.0.2

    3. 定制困难
    第三方组件库虽然功能强大，但对于深度定制的需求，往往需要复杂的配置和样式覆盖。

    shadcn 的解决方案

    shadcn 提出了一个颠覆性的理念：“Copy and paste, not install”

    # 传统方式：安装复杂依赖
npm install @tanstack/react-table @headlessui/react @heroicons/react

# shadcn 方式：复制可控代码
pnpm dlx shadcn@latest add https://erishen.github.io/shadcn-registry/r/data-table.json

    核心优势：

    1. 零依赖

    • 组件代码直接集成到项目中
    • 无需担心版本冲突和依赖更新

    2. 完全可控

    • 可以查看和修改每一行代码
    • 适应特定的设计系统和业务需求

    3. 精确控制

    • Tree-shaking 的极致实现
    • 只包含实际使用的代码

    4. 类型安全

    • 完整的 TypeScript 支持
    • 编译时错误检查

    项目架构：组件注册表的设计

    注册表系统架构

    shadcn-registry/
├── app/                          # Next.js App Router
│   ├── layout.tsx                # 根布局
│   ├── page.tsx                  # 主页（组件展示）
│   └── globals.css               # 全局样式
├── components/                   # 自定义组件
│   ├── ComponentPreview.tsx     # 组件预览
│   ├── DataTable.tsx            # 高级数据表格
│   └── ...
├── registry/                     # 注册表定义（核心）
│   ├── new-york/                # New York 主题
│   │   ├── blocks/              # 块级组件
│   │   └── ui/                  # 基础 UI 组件
│   ├── demo/                    # 演示组件
│   ├── styled-components/        # styled-components 示例
│   └── scss-components/          # SCSS 示例
├── stories/                      # Storybook 故事
├── public/r/                     # 注册表 JSON 文件
└── registry.json                 # 注册表配置

    核心配置文件

    registry.json 是整个系统的核心：

    {
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "erishen",
  "homepage": "https://erishen.github.io/shadcn-registry/",
  "items": [
    {
      "name": "data-table",
      "type": "registry:component",
      "title": "Data Table",
      "description": "A feature-rich data table with sorting, filtering, and pagination",
      "dependencies": ["button", "input"],
      "files": [
        {
          "path": "components/data-table.tsx",
          "type": "registry:component"
        }
      ]
    },
    {
      "name": "button",
      "type": "registry:ui",
      "title": "Button",
      "description": "A versatile button component with multiple variants",
      "dependencies": ["@radix-ui/react-slot", "class-variance-authority"],
      "files": [
        {
          "path": "registry/new-york/ui/button.tsx",
          "type": "registry:ui"
        }
      ]
    }
  ]
}

    组件分发机制

    # 一键安装任何组件
pnpm dlx shadcn@latest add https://erishen.github.io/shadcn-registry/r/data-table.json

# 系统会自动：
# 1. 下载组件源码
# 2. 安装必要依赖
# 3. 生成类型定义
# 4. 更新项目配置

    DataTable 组件：理念的实际应用

    为什么选择 DataTable？

    DataTable 是企业级应用中最复杂的组件之一，它能够很好地展示 shadcn 理念的优势：

    传统表格组件的依赖负担：

    • @tanstack/react-table：核心表格逻辑
    • @headlessui/react：UI 组件
    • @heroicons/react：图标库
    • clsx, tailwind-merge：样式工具
    • 总计：15+ 个依赖包，200KB+ 体积

    shadcn 方式：

    • 1 个文件，8KB 体积
    • 0 额外依赖
    • 完全可控的源码

    核心实现思路

    'use client';

import { useState, useMemo } from 'react';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';

// 强类型定义
export interface Column<T> {
  key: keyof T;
  label: string;
  sortable?: boolean;
  filterable?: boolean;
  render?: (value: T[keyof T], row: T) => React.ReactNode;
}

export interface DataTableProps<T extends Record<string, any>> {
  data: T[];
  columns: Column<T>[];
  pageSize?: number;
  onRowClick?: (row: T) => void;
}

// 性能优化：useMemo 缓存
const filteredData = useMemo(() => {
  return data.filter((row) => {
    return Object.entries(filters).every(([key, value]) => {
      if (!value) return true;
      const cellValue = String(row[key as keyof T]).toLowerCase();
      return cellValue.includes(value.toLowerCase());
    });
  });
}, [data, filters]);

    设计亮点：

    1. 三级排序循环

    const handleSort = (key: keyof T) => {
  if (sortKey === key) {
    if (sortDirection === 'asc') {
      setSortDirection('desc');
    } else if (sortDirection === 'desc') {
      setSortDirection(null);
      setSortKey(null);
    }
  } else {
    setSortKey(key);
    setSortDirection('asc');
  }
};

    2. 自定义渲染

    {
  key: 'status',
  label: '状态',
  render: (value) => (
    <span className={`px-2 py-1 rounded-full text-xs font-medium ${
      value === 'active' ? 'bg-green-100 text-green-800' : 'bg-red-100 text-red-800'
    }`}>
      {value === 'active' ? '激活' : '禁用'}
    </span>
  ),
}

    实际应用：interview/apps/web 项目集成

    安装过程

    # 从我们的注册表安装 data-table 组件
pnpm dlx shadcn@latest add https://erishen.github.io/shadcn-registry/r/data-table.json

    实际使用案例

    在 interview 项目中，我们用 DataTable 展示产品数据：

    interface Product {
  id: number;
  name: string;
  description?: string;
  price: number;
  category?: string;
  created_at?: string;
  is_offer?: boolean;
}

const columns: Array<Column<Product>> = [
  {
    key: 'name',
    label: 'Product Name',
    sortable: true,
    filterable: true,
  },
  {
    key: 'price',
    label: 'Price (¥)',
    sortable: true,
    render: (value: string | number | boolean | undefined) => `¥${Number(value).toFixed(2)}`,
  },
  {
    key: 'is_offer',
    label: 'Offer',
    sortable: true,
    filterable: true,
    render: (value: string | number | boolean | undefined) => {
      const isOffer = Boolean(value);
      return isOffer ? (
        <span className="px-2 py-1 rounded-full text-xs font-medium bg-red-100 text-red-800">
          特惠
        </span>
      ) : (
        <span className="text-slate-400">-</span>
      );
    },
  },
];

    集成优势：

    1. 快速开发：从安装到使用只需 5 分钟
    2. 完全定制：根据业务需求调整样式和逻辑
    3. 类型安全：TypeScript 完整的类型检查
    4. 性能优异：useMemo 优化，大数据量下依然流畅

    性能测试与对比

    综合性能测试

    我进行了详细的性能对比测试：

    测试环境：

    • MacBook Pro M1, 16GB RAM
    • Next.js 14 + React 18
    • 包含 20 个组件的中等规模项目

    测试结果：

    环节传统方式 (npm)shadcn + Bun提升幅度
    项目初始化45s3s15x
    依赖安装180s12s15x
    开发启动8.5s1.2s7x
    热重载450ms120ms3.7x
    生产构建120s25s4.8x

    实际项目对比：

    # 传统方式 (npm)
npm install           # 45秒
npm run dev           # 8.5秒启动
npm run build         # 2分钟构建
总时间: 2分53.5秒

# shadcn + Bun 方式
bun install           # 2秒！
bun run dev           # 1.2秒启动！
bun run build         # 25秒构建！
总时间: 28.2秒

# 效率提升: 6.1 倍！

    开发者体验提升

    速度提升只是表面，更重要的是开发体验的改善：

    // 传统方式：复杂的依赖管理
const traditionalPain = {
  install_waiting: "每次安装都要等待 1-3 分钟",
  version_conflicts: "经常遇到依赖版本冲突",
  bundle_size: "node_modules 动辄 500MB+",
  debugging: "第三方组件调试困难"
};

// shadcn 方式：极简高效
const shadcnExperience = {
  instant_feedback: "修改代码立即生效",
  zero_conflicts: "无依赖冲突问题",
  minimal_size: "精确控制代码体积",
  full_control: "源代码级别调试"
};

    部署与分发

    GitHub Pages 自动部署

    项目配置了完整的 CI/CD 流程：

    # .github/workflows/deploy.yml
name: Deploy to GitHub Pages
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest
      - run: bun install
      - run: bun run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./out

    组件分发体验

    # 其他开发者可以这样使用我们的组件
pnpm dlx shadcn@latest add https://erishen.github.io/shadcn-registry/r/data-table.json

# 或者从本地开发
pnpm dlx shadcn@latest add http://localhost:3000/r/data-table.json

    深度思考：前端开发的未来

    传统开发模式的局限

    在构建这个项目的过程中，我深刻反思了传统前端开发的几个问题：

    1. 效率问题
    npm 的安装速度已经成为开发效率的瓶颈，每次 npm install 都是对开发者耐心的考验。

    2. 依赖复杂性
    一个简单的项目往往需要几十个依赖包，不仅增加了项目复杂度，也带来了安全隐患。

    3. 定制困难
    第三方组件库虽然功能强大，但深度定制往往需要复杂的配置和样式覆盖。

    新范式的优势

    1. 开发者体验优先

    // shadcn 理念：开发者体验至上
const devExperience = {
  installation: "一键安装，无需等待",
  customization: "源代码级别的定制",
  debugging: "完整的调试支持",
  performance: "极致的性能优化"
};

    2. 工具链优化

    // Bun 代表的工具链优化方向
const toolingEvolution = {
  packageManager: "从 npm 到 Bun 的性能革命",
  bundling: "原生性能的构建工具",
  testing: "一体化的测试解决方案",
  typeChecking: "原生的 TypeScript 支持"
};

    3. 社区生态

    // 组件注册表模式推动的生态发展
const ecosystemImpact = {
  componentSharing: "组件共享的新模式",
  standardization: "行业标准的建立",
  qualityAssurance: "开源组件的质量保证",
  innovation: "快速迭代的创新机制"
};

    对行业的影响

    我认为 shadcn + Bun 的组合代表了前端工具链发展的几个重要趋势：

    1. 性能优先
    开发者工具的性能不再是可有可无的优化，而是核心竞争力。

    2. 开发者体验
    工具设计越来越注重开发者的感受，从功能导向转向体验导向。

    3. 定制能力
    标准化与定制化的平衡成为设计的重要考量。

    4. 生态协作
    开源社区的协作模式不断创新，组件共享成为新的发展趋势。

    技术亮点总结

    1. 性能优化策略

    useMemo 缓存模式

    // 数据过滤优化
const filteredData = useMemo(() => {
  return data.filter((row) => {
    return Object.entries(filters).every(([key, value]) => {
      if (!value) return true;
      const cellValue = String(row[key as keyof T]).toLowerCase();
      return cellValue.includes(value.toLowerCase());
    });
  });
}, [data, filters]);

    精确的依赖数组

    // 避免不必要的重新计算
const sortedData = useMemo(() => {
  if (!sortKey || !sortDirection) return filteredData;
  
  return [...filteredData].sort((a, b) => {
    const aVal = a[sortKey];
    const bVal = b[sortKey];
    
    if (aVal < bVal) return sortDirection === 'asc' ? -1 : 1;
    if (aVal > bVal) return sortDirection === 'asc' ? 1 : -1;
    return 0;
  });
}, [filteredData, sortKey, sortDirection]);

    2. 类型安全设计

    泛型约束

    export function DataTable<T extends Record<string, any>>({
  data,
  columns,
  pageSize = 10,
  onRowClick,
}: DataTableProps<T>) {
  // 完整的类型安全保障
}

    接口定义

    export interface Column<T> {
  key: keyof T;
  label: string;
  sortable?: boolean;
  filterable?: boolean;
  render?: (value: T[keyof T], row: T) => React.ReactNode;
}

    3. 用户体验优化

    加载状态处理

    {loading && (
  <div className="flex justify-center items-center py-16">
    <div className="animate-spin rounded-full h-14 w-14 border-4 border-slate-200 border-t-blue-600"></div>
  </div>
)}

    错误边界

    {error && (
  <div className="bg-red-50 border border-red-200 rounded p-6">
    <p className="text-red-800">加载失败: {error}</p>
    <button onClick={() => loadProducts()}>重试</button>
  </div>
)}

    总结与展望

    项目收获

    通过 shadcn-registry 项目，我收获的不仅仅是一个组件库，更重要的是对前端开发效率的深度思考：

    1. 工具选择的重要性
    好的工具能够让开发效率产生数量级的提升，Bun 就是这样的工具。

    2. 开发理念的革新
    shadcn 的 “copy instead of install” 理念颠覆了我对依赖管理的认知。

    3. 性能优化的必要性
    前端性能优化不仅仅是用户体验的需求，也是开发者体验的重要组成。

    4. 开源协作的价值
    通过开源分享，我们能够推动整个行业的进步。

    对未来的思考

    1. 工具链的发展方向
    我认为前端工具链会朝着更快、更简单、更强大的方向发展。Bun 只是一个开始，未来还会有更多性能突破。

    2. 组件生态的演进
    组件注册表模式可能会重新定义开源组件的分发和协作方式。

    3. 开发效率的新标准
    随着工具的不断优化，开发者对效率的期望也会不断提高。

    4. 技术民主化的趋势
    好的工具和理念应该让更多的开发者受益，而不是成为少数人的特权。

    实际应用价值

    对于团队：

    • 统一的组件标准
    • 提升的开发效率
    • 降低的维护成本
    • 更好的代码质量

    对于个人：

    • 更快的开发反馈
    • 更强的定制能力
    • 更好的学习体验
    • 更高的技术视野

    资源链接

    写这篇文章的过程中，我深刻感受到了技术变革的力量。有时候，一个理念的转变就能带来效率的数量级提升。shadcn + Bun 的组合不仅仅是工具的升级，更是开发方式的革新。

    希望这篇文章能够给同样关注开发效率的朋友们一些启发。如果你也在思考如何提升前端开发效率，欢迎在评论区交流讨论。

  • 从零构建全栈技术知识库平台：Monorepo + Next.js 14 + FastAPI 实践

    基于 Turborepo + Next.js 14 + FastAPI 的全栈开发实践，适合中小型项目的架构设计和部署方案。

    项目背景与定位

    在多年的开发实践中，我发现自己积累的技术知识点往往零散分布在各个项目和学习笔记中。为了系统化梳理这些知识，我决定构建一个技术知识库平台。

    核心需求：

    • 统一管理学习笔记和技术文档
    • 支持在线编辑和实时预览
    • 提供优雅的文档展示体验
    • 作为一个技术实践项目，探索全栈开发最佳实践

    这个项目不仅满足了个人知识管理的需求，也希望通过开源分享，给其他开发者提供参考。

    项目定位

    这是一个中小型全栈项目，重点展示：

    • Monorepo 架构在非超大规模项目中的应用
    • Next.js 14 + FastAPI 的技术选型和开发实践
    • Docker 容器化部署到生产环境的完整流程
    • 技术知识库系统的设计与实现

    适合场景：

    • 个人技术博客和知识库
    • 小团队的全栈项目架构参考
    • 学习 Next.js 14 和 FastAPI 的实践案例

    技术选型与架构设计

    为什么选择 Monorepo？

    在项目初期，我面临一个关键决策：是采用传统的多仓库（Multi-repo）架构，还是选择 Monorepo？

    最终选择 Turborepo + Monorepo 架构，主要基于以下考量：

    维度Multi-repoMonorepo
    代码共享需要发布 npm 包workspace 直接引用
    版本管理各仓库独立版本统一版本控制
    CI/CD多个流水线单一构建流程
    依赖管理容易版本冲突统一依赖管理
    跨包测试困难简单直接

    核心技术栈

    ├── 前端框架层
│   ├── Next.js 14 (App Router)   # React 全栈框架
│   ├── React 18                  # UI 库
│   └── TypeScript 5              # 类型安全
│
├── 后端框架层
│   ├── FastAPI                  # Python 异步 Web 框架
│   ├── Python 3.10+             # 运行时
│   ├── Pydantic                 # 数据验证
│   ├── SQLAlchemy               # ORM
│   ├── Alembic                  # 数据库迁移
│   └── Uvicorn                  # ASGI 服务器
│
├── 数据存储
│   ├── MySQL 8.0               # 关系型数据库
│   ├── Redis                   # 缓存与会话
│   └── Supabase                # 云数据库 + 认证
│
├── 内容渲染
│   ├── next-mdx-remote         # MDX/Markdown 渲染
│   └── @tailwindcss/typography # 文档样式插件
│
├── 构建工具
│   ├── Turborepo             # Monorepo 构建工具
│   ├── pnpm                  # 高效的包管理器
│   └── Docker                # 容器化部署
│
├── 样式方案
│   ├── Tailwind CSS             # 原子化 CSS
│   └── styled-components        # CSS-in-JS
│
├── 开发工具
│   ├── ESLint + Prettier       # 代码规范
│   ├── Storybook               # 组件开发
│   └── Changeset               # 版本管理
│
└── 部署平台
    ├── Vercel                   # Serverless 前端部署
    ├── Docker + Linux           # 后端容器化部署
    └── Nginx                    # 反向代理

    项目架构

    ┌─────────────────────────────────────────────────────────────┐
│                    用户访问层                                 
│  web.erishen.cn (前端)  │  admin.erishen.cn (后台)       
│  (Interview Web)          │  (Interview Admin)            
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│                    API 网关层                             
│              api.erishen.cn (FastAPI)                     
│  - 商品管理 API (Items API)                                
│  - 认证 API (Auth API)                                    
│  - 文档 API (Docs API)                                     
│  - Redis API (缓存服务)                                     
└─────────────────────────────────────────────────────────────┘
                           ↓
        ┌──────────────────┴──────────────────┐
        ↓                                     ↓
┌──────────────────┐              ┌──────────────────┐
│   MySQL 8.0     │               │     Redis       
│   商品/文档数据   │               │    缓存/会话      
└──────────────────┘              └──────────────────┘

    项目结构

    ┌─────────────────────────────────────────────────────────────┐
│              Interview (前端 Monorepo)                       
├─────────────────────────────────────────────────────────────┤
│  apps/                                                     
│  ├── web/              # 主应用 (端口 3000)              
│  │   └── src/                                            
│  │       ├── app/                                           
│  │       │   ├── docs/                 # 文档展示系统     
│  │       │   │   ├── page.tsx         # 文档列表         
│  │       │   │   └── [slug]/page.tsx  # 文档详情        
│  │       │   ├── api-integration/     # API 集成演示     
│  │       │   └── ...                                         
│  │       └── lib/                                           
│  │           └── docs.ts              # 文档加载工具     
│  └── admin/            # 管理后台 (端口 3003)          
│                                                             
│  packages/                                                  
│  ├── ui/               # 共享 UI 组件库                  
│  ├── api-client/       # API 客户端                      
│  ├── utils/            # 工具函数                         
│  ├── types/            # 类型定义                         
│  ├── config/           # 配置文件                         
│  └── constants/        # 常量定义                        
│                                                             
│  docs/                 # 知识库文档 (Markdown 源文件)      
│  ├── README.md                      # 文档导航           
│  ├── frontend.md                    # 前端基础知识       
│  ├── frontend-extended.md           # 前端扩展知识       
│  ├── dynamic-programming.md         # 动态规划           
│  ├── case1.md                      # 综合题库           
│  └── ...                                                       
│                                                             
│  scripts/              # 工具脚本                          
│  turbo.json           # Turborepo 配置                    
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│              fastapi-web (后端服务)                           
├─────────────────────────────────────────────────────────────┤
│  app/                                                       
│  ├── main.py                 # FastAPI 应用入口             
│  ├── routers/                # API 路由层               
│  │   ├── items.py        # 商品 API                   
│  │   ├── auth.py         # 认证 API                   
│  │   ├── docs.py         # 文档 API                   
│  │   ├── redis.py        # Redis API                  
│  │   └── system.py      # 系统 API                   
│  ├── config.py               # 配置管理                   
│  ├── crud.py                # 数据库 CRUD 操作             
│  ├── models.py              # 数据模型层 (SQLAlchemy)       
│  │   ├── Item            # 商品模型                   
│  │   └── DocLog         # 文档日志模型                
│  ├── schemas.py             # Pydantic 数据验证           
│  ├── security.py            # 安全工具（JWT、认证）       
│  ├── security_headers.py     # 安全响应头                  
│  ├── middleware.py         # 中间件（日志、限流）       
│  ├── ip_filter.py          # IP 黑名单/白名单过滤        
│  ├── path_protection.py    # 敏感路径保护               
│  ├── redis_client.py       # Redis 客户端                
│  ├── database.py           # 数据库连接                  
│  ├── exceptions.py         # 异常处理                    
│  └── factory.py           # 应用工厂                    
│                                                             
│  alembic/                # 数据库迁移                       
│  tests/                  # 测试用例                        
│  requirements.txt         # Python 依赖                     
│  Dockerfile              # 容器构建配置                    
│  docker-compose.yml      # Docker Compose 配置              
└─────────────────────────────────────────────────────────────┘

    核心功能模块

    1. Web 应用（前端知识库）

    Web 应用是项目的主入口，提供完整的面试知识库浏览和搜索功能：

    • 知识库导航：结构化的文档分类展示
    • 文档渲染：基于 next-mdx-remote 的 Markdown 实时渲染
    • 自动加载：从 Admin API 或本地文件系统获取文档
    • 代码高亮：优雅的代码块展示和语法高亮
    • 搜索功能：基于关键词的快速检索
    • 响应式设计：适配移动端和桌面端

    文档展示系统实现

    文档加载逻辑

    文档内容通过 Admin API 获取，构建时回退到本地文件系统：

    // src/lib/docs.ts
import fs from 'fs';
import path from 'path';

export interface Doc {
  slug: string;
  title: string;
  description?: string;
}

const DOCS_DIR = path.join(process.cwd(), '../../docs');
const ADMIN_API_URL = process.env.NEXT_PUBLIC_ADMIN_URL || 'http://localhost:3003';
const DOCS_API_ENDPOINT = `${ADMIN_API_URL}/api/docs-public`;

// 从 Admin API 获取文档列表（生产环境）
async function fetchDocsFromAdmin(): Promise<Doc[]> {
  try {
    const response = await fetch(DOCS_API_ENDPOINT, {
      cache: 'no-store',
      headers: {
        'Referer': process.env.NEXT_PUBLIC_WEB_URL || 'http://localhost:3000',
        'Origin': process.env.NEXT_PUBLIC_WEB_URL || 'http://localhost:3000',
      },
    });
    const data = await response.json();
    return data.success ? data.docs : [];
  } catch (error) {
    console.error('[Docs API] Error fetching docs from Admin:', error);
    return [];
  }
}

// 从本地文件系统获取文档列表（构建时回退）
function getLocalDocs(): Doc[] {
  if (!fs.existsSync(DOCS_DIR)) {
    return [];
  }

  const files = fs.readdirSync(DOCS_DIR);
  return files
    .filter(file => file.endsWith('.md'))
    .map(file => {
      const slug = file.replace(/\.md$/, '');
      const content = fs.readFileSync(path.join(DOCS_DIR, file), 'utf-8');
      const titleMatch = content.match(/^#\s+(.+)$/m);
      return {
        slug,
        title: titleMatch ? titleMatch[1] : slug,
        description: content.match(/^> (.+)$/m)?.[1]
      };
    });
}

// 获取所有文档（生产环境优先 Admin API，构建时或开发环境优先本地）
export async function getAllDocs(): Promise<Doc[]> {
  const isProduction = process.env.NODE_ENV === 'production';
  const isBuildTime = process.env.NEXT_PHASE?.includes('build');

  // 构建时或开发环境：优先本地文件
  if (isBuildTime || !isProduction) {
    const localDocs = getLocalDocs();
    if (localDocs.length > 0) return localDocs;
    return await fetchDocsFromAdmin();
  }

  // 生产环境：优先从 Admin API，失败则降级到本地文件
  const adminDocs = await fetchDocsFromAdmin();
  if (adminDocs.length > 0) return adminDocs;
  return getLocalDocs();
}

// 获取单个文档
export async function getDocBySlug(slug: string): Promise<string | null> {
  const isProduction = process.env.NODE_ENV === 'production';
  const isBuildTime = process.env.NEXT_PHASE?.includes('build');

  async function fetchDocFromAdmin(slug: string): Promise<string | null> {
    try {
      const url = new URL(DOCS_API_ENDPOINT);
      url.searchParams.set('slug', slug);
      const response = await fetch(url.toString(), { cache: 'no-store' });
      const data = await response.json();
      return data.success ? data.doc.content : null;
    } catch (error) {
      console.error(`[Docs API] Error fetching doc ${slug}:`, error);
      return null;
    }
  }

  function getLocalDocBySlug(slug: string): string | null {
    const filePath = path.join(DOCS_DIR, `${slug}.md`);
    return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : null;
  }

  // 构建时或开发环境：优先本地文件
  if (isBuildTime || !isProduction) {
    const localDoc = getLocalDocBySlug(slug);
    if (localDoc) return localDoc;
    return await fetchDocFromAdmin(slug);
  }

  // 生产环境：优先从 Admin API
  const adminDoc = await fetchDocFromAdmin(slug);
  if (adminDoc) return adminDoc;
  return getLocalDocBySlug(slug);
}

    文档列表页面

    // src/app/docs/page.tsx
import { getAllDocs } from '@/lib/docs';
import Link from 'next/link';

export default async function DocsPage() {
  const docs = await getAllDocs();

  // 按分类展示
  const coreDocs = docs.filter(doc => ['frontend', 'frontend-extended'].includes(doc.slug));
  const algorithmDocs = docs.filter(doc => 
    ['dynamic-programming', 'min-path-sum-explained'].includes(doc.slug)
  );

  return (
    <div className="container mx-auto">
      <h1>📚 前端面试知识库</h1>

      <section>
        <h2>🎯 核心基础知识</h2>
        {coreDocs.map(doc => (
          <Link key={doc.slug} href={`/docs/${doc.slug}`}>
            <Card title={doc.title} description={doc.description} />
          </Link>
        ))}
      </section>

      <section>
        <h2>🧮 算法与数据结构</h2>
        {algorithmDocs.map(doc => (
          <Link key={doc.slug} href={`/docs/${doc.slug}`}>
            <Card title={doc.title} description={doc.description} />
          </Link>
        ))}
      </section>
    </div>
  );
}

    文档详情页面

    // src/app/docs/[slug]/page.tsx
import { getDocBySlug } from '@/lib/docs';
import { MDXRemote } from 'next-mdx-remote/rsc';

export default async function DocDetailPage({ params }: { params: { slug: string } }) {
  const content = await getDocBySlug(params.slug);

  if (!content) return <div>文档未找到</div>;

  return (
    <article className="prose prose-slate prose-lg max-w-none">
      <MDXRemote source={content} />
    </article>
  );
}

    2. Admin 应用（技术演示平台）

    Admin 应用是一个企业级技术演示平台，用于展示和验证多种前端/后端技术：

    • 文档编辑器：在线编辑 docs/ 目录下的 Markdown 文档
      • 实时文档列表展示
      • 在线 Markdown 编辑
      • 创建新文档
      • 实时预览效果
      • 通过 Admin API 向 Web 应用提供文档内容
    • 双认证系统：NextAuth.js 和 Passport.js 两种认证方式对比演示
    • 安全验证：CSRF 保护、Lusca 安全中间件
    • 缓存演示：Redis 连接和缓存操作
    • API 集成：FastAPI 服务代理和跨服务通信
    • 管理后台模板：Dashboard UI 和统计数据展示

    3. FastAPI 后端服务

    FastAPI 后端提供完整的 RESTful API 服务：

    • 商品管理 API：完整的 CRUD 操作
      • 商品列表查询（分页、搜索）
      • 商品详情获取
      • 商品创建和更新（需管理员权限）
      • 商品删除（需管理员权限）
    • 认证 API：JWT 认证和用户管理
      • 登录认证
      • Token 验证
      • 权限控制
    • 文档 API：知识库文档服务
      • 文档列表和详情
      • 文档操作日志
      • 编辑权限控制
      • 实时预览
    • Redis API：缓存操作演示
      • 键值存储
      • 缓存管理
    • 系统 API：健康检查和系统信息

    计划中的功能

    以下功能已规划实现，当前处于开发阶段：

    • 实时通信：WebSocket 支持（计划中）
      • 健康度评分系统
      • 在线状态推送
    • 安全机制：
      • JWT 令牌认证
      • 速率限制（防止 DDoS）
      • 可疑访问检测和告警
      • CORS 跨域配置
    • 性能优化：
      • Redis 缓存层
      • 数据库连接池
      • 异步 I/O 处理
      • Gzip 压缩响应

    FastAPI 实现代码示例

    路由定义（商品 API）

    # app/routers/items.py
from fastapi import APIRouter, HTTPException, Depends, Query
from sqlalchemy.orm import Session
from typing import List, Optional
from .. import crud, schemas
from ..database import get_db
from ..security import get_current_user, get_admin_user

router = APIRouter(
    prefix="/items",
    tags=["商品管理"],
    responses={404: {"description": "商品未找到"}}
)

@router.get("/", response_model=List[schemas.Item])
def read_items(
    skip: int = Query(0, ge=0, description="跳过的记录数"),
    limit: int = Query(10, ge=1, le=100, description="返回的记录数"),
    db: Session = Depends(get_db),
    current_user: Optional[dict] = Depends(lambda: None)  # 公开访问，无需认证
):
    """获取商品列表（公开访问）"""
    items = crud.get_items(db, skip=skip, limit=limit)
    return items

@router.get("/search", response_model=List[schemas.Item])
def search_items(
    keyword: str = Query(..., min_length=1, description="搜索关键词"),
    skip: int = Query(0, ge=0),
    limit: int = Query(10, ge=1, le=100),
    db: Session = Depends(get_db),
    current_user: Optional[dict] = Depends(lambda: None)  # 公开访问，无需认证
):
    """搜索商品（公开访问）"""
    items = crud.search_items(db, keyword=keyword, skip=skip, limit=limit)
    return items

@router.get("/{item_id}", response_model=schemas.Item)
def read_item(
    item_id: int,
    db: Session = Depends(get_db),
    current_user: Optional[dict] = Depends(lambda: None)  # 公开访问，无需认证
):
    """获取单个商品（公开访问）"""
    db_item = crud.get_item(db, item_id=item_id)
    if db_item is None:
        raise HTTPException(status_code=404, detail="商品未找到")
    return db_item

@router.post("/", response_model=schemas.Item, status_code=201)
def create_item(
    item: schemas.ItemCreate,
    db: Session = Depends(get_db),
    admin_user: dict = Depends(get_admin_user)  # 需要管理员权限
):
    """创建新商品"""
    return crud.create_item(db=db, item=item)

@router.put("/{item_id}", response_model=schemas.Item)
def update_item(
    item_id: int,
    item: schemas.ItemUpdate,
    db: Session = Depends(get_db),
    admin_user: dict = Depends(get_admin_user)  # 需要管理员权限
):
    """更新商品信息"""
    db_item = crud.update_item(db=db, item_id=item_id, item=item)
    if db_item is None:
        raise HTTPException(status_code=404, detail="商品未找到")
    return db_item

@router.delete("/{item_id}")
def delete_item(
    item_id: int,
    db: Session = Depends(get_db),
    admin_user: dict = Depends(get_admin_user)  # 需要管理员权限
):
    """删除商品"""
    success = crud.delete_item(db=db, item_id=item_id)
    if not success:
        raise HTTPException(status_code=404, detail="商品未找到")
    return {"message": "商品删除成功"}

    Pydantic 数据验证

    # app/schemas.py
from pydantic import BaseModel, Field
from typing import Union, Optional
from datetime import datetime

class ItemBase(BaseModel):
    name: str = Field(..., min_length=1, max_length=100, description="商品名称")
    price: float = Field(..., gt=0, description="商品价格，必须大于0")
    is_offer: Union[bool, None] = Field(default=None, description="是否为特价商品")
    description: Optional[str] = Field(None, max_length=1000, description="商品描述")

class ItemCreate(ItemBase):
    pass

class ItemUpdate(BaseModel):
    name: Optional[str] = Field(None, min_length=1, max_length=100)
    price: Optional[float] = Field(None, gt=0)
    is_offer: Optional[bool] = None
    description: Optional[str] = Field(None, max_length=1000)

class Item(ItemBase):
    id: int
    created_at: Optional[datetime] = None
    updated_at: Optional[datetime] = None

    class Config:
        from_attributes = True  # Pydantic v2 语法

    3. 共享组件库（packages/ui）

    在 Monorepo 架构中，共享组件库是提升开发效率的关键：

    // 任意应用中导入共享组件
import { Button, Card, Input } from "@interview/ui";

// 带类型提示和自动补全
<Button variant="primary" size="large">
  点击我
</Button>

    知识库内容体系

    文档结构

    整个知识库文档按难度和领域进行分类，形成完整的学习路径：

    docs/
├── README.md                      # 导航索引
├── frontend.md                    # 基础知识 (70KB)
├── frontend-extended.md           # 扩展知识 (46KB)
├── dynamic-programming.md         # 动态规划 (18KB)
├── min-path-sum-explained.md      # 最小路径和详解
├── frontend-algorithms-practical.md  # 实际工作算法
├── case1.md                      # 综合题库 (优化版)
├── styled-components-guide.md     # styled-components 指南
├── REDIS_USAGE.md                 # Redis 使用指南
└── PACKAGES_VS_SHARED.md          # 包与共享代码

    最新优化内容

    case1.md 综合题库优化亮点：

    1. 格式修正：修正编号错误，统一的文档结构
    2. 代码示例：每个问题都添加了详细的 TypeScript 代码
    3. 对比表格：多种技术方案的横向对比（如 LRU vs LFU、gRPC vs REST）
    4. 实战案例：第 8 题提供 3 个完整的 STAR 法则案例
    5. 完整实现：LRU/LFU 缓存的完整 TypeScript 实现
    6. 质量监控：WebSocket 健康度评分系统

    学习路径推荐

    初学者路径

    前端基础知识 → 实际工作中的算法 → 动态规划入门

    进阶开发者路径

    前端扩展知识 → 最小路径和详解 → 深入特定技术栈

    面试冲刺路径

    核心知识点 → 算法基础 → 深度拓展 → 实战经验 → 综合题库

    技术亮点与最佳实践

    1. 前端：Turborepo 构建优化

    // turbo.json
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

    优势：

    • 智能缓存机制，避免重复构建
    • 并行执行任务，提升构建速度
    • 依赖关系自动分析

    2. 后端：FastAPI 异步架构

    # app/factory.py
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from .routers import items, system, auth, redis, doc_logs

def create_app():
    """创建 FastAPI 应用实例"""

    app = FastAPI(
        title="FastAPI Web API",
        description="全栈演示平台后端服务",
        version="1.0.0",
        docs_url="/docs",
        redoc_url="/redoc"
    )

    # CORS 配置
    # 注意：allow_origins=["*"] 仅用于开发环境，生产环境请指定具体域名
    app.add_middleware(
        CORSMiddleware,
        allow_origins=["*"],  # 生产环境请改为 ["https://web.erishen.cn", ...]
        allow_credentials=True,
        allow_methods=["*"],
        allow_headers=["*"],
    )

    # 路由注册
    app.include_router(items.router, prefix="/items", tags=["商品管理"])
    app.include_router(auth.router, prefix="/auth", tags=["认证"])
    app.include_router(docs.router, prefix="/docs", tags=["文档"])
    app.include_router(redis.router, prefix="/redis", tags=["Redis"])
    app.include_router(system.router, tags=["系统"])

    return app

    优势：

    • 原生异步支持，高并发性能
    • 自动生成 OpenAPI 文档（Swagger）
    • 类型注解驱动的数据验证（Pydantic）
    • 内置依赖注入系统

    3. 后端：分层架构设计

    app/
├── routers/                # API 路由层
│   ├── items.py        # 商品 API
│   ├── auth.py         # 认证 API
│   ├── docs.py         # 文档 API
│   ├── redis.py        # Redis API
│   └── system.py      # 系统 API
├── config.py               # 配置管理
├── crud.py                # 数据库 CRUD 操作
├── models.py              # 数据模型层 (SQLAlchemy)
│   ├── Item            # 商品模型
│   └── DocLog         # 文档日志模型
├── schemas.py             # Pydantic 数据验证
├── security.py            # 安全工具（JWT、认证）
├── security_headers.py     # 安全响应头
├── middleware.py         # 中间件（日志、限流）
├── ip_filter.py          # IP 黑名单/白名单过滤
├── path_protection.py    # 敏感路径保护
├── redis_client.py       # Redis 客户端
├── database.py           # 数据库连接
├── exceptions.py         # 异常处理
└── factory.py           # 应用工厂

    优势：

    • 职责分离，易于维护和测试
    • 业务逻辑独立于 API 接口
    • 可复用的服务层
    • 灵活的中间件扩展

    4. 安全机制：多层级防护

    # app/middleware.py
from fastapi import Request, Response
from .security import is_suspicious_request

async def security_middleware(request: Request, call_next):
    # 1. 可疑访问检测
    if is_suspicious_request(request):
        logger.warning(f"⚠️  可疑访问检测: IP={request.client.host}")
        return Response(status_code=403)

    # 2. 速率限制
    if await rate_limiter.is_exceeded(request):
        logger.warning(f"🚫  速率限制: IP={request.client.host}")
        return Response(
            content="Too many requests",
            status_code=429
        )

    # 3. 日志记录
    logger.info(f"{request.method} {request.url.path}")
    response = await call_next(request)
    return response

    防护措施：

    • ✅ JWT 令牌认证
    • ✅ 速率限制（防止滥用）
    • ✅ 可疑访问检测
    • ✅ CORS 跨域控制
    • ✅ SQL 注入防护（ORM）
    • ✅ XSS 防护（输入验证）

    2. MDX/Markdown 渲染方案

    使用 next-mdx-remote + @tailwindcss/typography 实现优雅的文档渲染：

    // 安装依赖
pnpm add next-mdx-remote @tailwindcss/typography

// Tailwind 配置
// tailwind.config.js
module.exports = {
  plugins: [require('@tailwindcss/typography')],
};

// 使用 Tailwind Typography 类
<article className="prose prose-slate prose-lg max-w-none">
  <MDXRemote source={content} />
</article>

    支持的 Markdown 特性：

    • ✅ 标题（H1-H6）
    • ✅ 代码块和语法高亮
    • ✅ 表格
    • ✅ 引用块
    • ✅ 列表（有序/无序）
    • ✅ 粗体、斜体
    • ✅ 链接和图片
    • ✅ 分隔线

    3. Workspace 协议

    {
  "dependencies": {
    "@interview/ui": "workspace:*",
    "@interview/utils": "workspace:*"
  }
}

    使用 workspace:* 协议可以实现：

    • 开发时实时引用源码
    • 构建时自动链接
    • 版本统一管理

    4. 环境变量管理

    项目支持多环境配置：

    # .env.example          # 模板文件
# .env.local            # 本地开发（不提交）
# .env.vercel           # Vercel 部署

    5. 组件开发流程

    使用 Storybook 进行组件开发：

    # 启动 Storybook
pnpm storybook

# 构建静态文档
pnpm build-storybook

    优势：

    • 组件独立开发
    • 实时预览效果
    • 文档自动生成

    开发体验优化

    1. 统一的代码规范

    // .eslintrc.js
module.exports = {
  extends: ["@interview/eslint-config"]
}

    2. 类型安全保障

    TypeScript 配置支持路径别名：

    // tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@interview/ui": ["./packages/ui/src"]
    }
  }
}

    3. 实用工具脚本

    # 清理端口占用
pnpm kill-ports

# 清理数据库连接
pnpm clean-connections

    部署与运维

    前端部署：Vercel

    项目配置了 Vercel 自动部署：

    // vercel.json
{
  "buildCommand": "pnpm build",
  "installCommand": "pnpm install"
}

    部署环境：

    部署特点：

    • ✅ 自动化 CI/CD（Git 推送自动部署）
    • ✅ Serverless 函数（按需付费）
    • ✅ 全球 CDN 加速
    • ✅ 自动 HTTPS 证书

    后端部署：Docker + Linux

    FastAPI 后端采用 Docker 容器化部署到 Linux 服务器：

    # docker-compose.prod.yml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: fastapi-web-app
    network_mode: host
    restart: always
    environment:
      - APP_ENV=production
      - PORT=8086
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
    volumes:
      - ./app:/app/app
      - ./logs:/app/logs
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8086/health"]
      interval: 30s
      retries: 3

    部署环境：

    部署特点：

    • ✅ Docker 容器化（环境一致性）
    • ✅ 容器自动重启（restart: always）
    • ✅ 健康检查（自动恢复）
    • ✅ Nginx 反向代理
    • ✅ SSL/TLS 加密通信

    数据库设计

    MySQL 关系型数据库

    -- 商品表
CREATE TABLE items (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    description TEXT,
    price FLOAT NOT NULL,
    is_offer INT DEFAULT 0,  -- 0=False, 1=True
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- 文档操作日志表
CREATE TABLE doc_logs (
    id INT AUTO_INCREMENT PRIMARY KEY,
    action VARCHAR(50) NOT NULL,  -- 操作类型: create/update/delete
    doc_slug VARCHAR(100) NOT NULL,
    user_id VARCHAR(100),
    user_email VARCHAR(100),
    user_name VARCHAR(100),
    auth_method VARCHAR(50),  -- 认证方式: nextauth/passport
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    details TEXT
);

-- 索引优化
CREATE INDEX idx_items_name ON items(name);
CREATE INDEX idx_doc_logs_slug ON doc_logs(doc_slug);
CREATE INDEX idx_doc_logs_user ON doc_logs(user_id);

    Redis 缓存策略

    # app/redis_client.py
from redis import Redis
from json import dumps, loads

class RedisClient:
    def __init__(self):
        self.redis = Redis(
            host=os.getenv("REDIS_HOST", "localhost"),
            port=int(os.getenv("REDIS_PORT", "6379")),
            password=os.getenv("REDIS_PASSWORD"),
            decode_responses=True
        )

    # 缓存商品列表（TTL 5 分钟）
    async def cache_products(self, products: list):
        await self.redis.setex(
            "products:list",
            300,
            dumps(products)
        )

    # 缓存用户会话（TTL 30 分钟）
    async def cache_session(self, user_id: int, session: dict):
        await self.redis.setex(
            f"session:{user_id}",
            1800,
            dumps(session)
        )

    # 缓存文档内容（TTL 10 分钟）
    async def cache_doc(self, slug: str, content: str):
        await self.redis.setex(
            f"doc:{slug}",
            600,
            content
        )

    缓存策略：

    • 商品列表：5 分钟（热点数据）
    • 用户会话：30 分钟
    • 文档内容：10 分钟
    • 系统配置：1 小时

    开发环境启动

    # 安装依赖
pnpm install

# 启动所有应用
pnpm dev

# 启动单个应用
pnpm dev --filter=@interview/web

# 访问文档列表
open http://localhost:3000/docs

    项目收益与反思

    收益

    1. 全栈技术沉淀：系统梳理了前后端知识体系
    2. 工程化实践：掌握了 Monorepo + Docker 完整架构
    3. 学习效率：快速查找技术相关知识点
    4. 分享价值：帮助他人学习成长
    5. 文档系统：优雅的 Markdown 展示体验
    6. 实战经验：完成完整的产品开发流程

    反思与改进

    1. 文档维护成本：内容更新需要持续投入
    2. 性能优化：大文档加载体验有待优化（可考虑分块加载）
    3. 社区参与：缺乏互动机制和用户反馈
    4. 搜索功能：可以增加全文搜索和智能推荐
    5. 后端监控：需要添加性能监控和告警系统
    6. 容器编排：未来可考虑 Kubernetes 集群部署

    未来规划

    前端优化

    • [ ] 添加全文搜索功能（ElasticSearch）
    • [ ] 支持文档评论和互动
    • [ ] 实现深色模式
    • [ ] 添加阅读进度和书签功能
    • [ ] 支持导出 PDF
    • [ ] 数据埋点，用户访问信息记录

    后端优化

    • [ ] WebSocket 实时通信功能（计划中）
    • [ ] 健康度评分系统（计划中）
    • [ ] 添加性能监控（Prometheus + Grafana）
    • [ ] 实现分布式追踪（Jaeger）
    • [ ] 添加消息队列（RabbitMQ/Celery）
    • [ ] 优化数据库查询（读写分离）
    • [ ] 实现 GraphQL API（计划中）

    运维优化

    • [ ] CI/CD 自动化流程优化
    • [ ] 容器编排迁移到 Kubernetes
    • [ ] 自动化测试覆盖率提升
    • [ ] 灰度发布和回滚机制

    项目局限性

    为了保持文章的真实性，这里也说明一下当前项目的局限性：

    1. 项目规模较小：这不是一个超大规模的系统，API 数量和业务复杂度有限
    2. 缺少单元测试：当前项目还没有完整的单元测试覆盖
    3. 未实现所有计划功能：WebSocket、性能监控等功能仍在规划中
    4. 性能数据缺失：没有做过高并发压力测试和性能基准测试
    5. 团队协作场景未验证：主要是个人项目，多团队协作的场景未充分验证

    这个案例更适合作为中小型项目的架构参考，而不是超大规模系统的解决方案。如果你的项目规模更大，需要考虑更复杂的架构设计。

    总结

    这个项目是我的一个全栈开发实践案例，通过构建技术知识库，我总结了以下几点经验：

    • Monorepo 适合中小团队：代码共享、统一依赖，但在超大规模项目时要谨慎评估
    • 技术选型要务实：Next.js 14 + FastAPI 对于中小型项目是高效的选择
    • 工程化很重要：Turborepo、Docker、CI/CD 能显著提升开发效率和部署可靠性
    • 从简单开始迭代：先实现核心功能，再逐步完善（如后续计划添加的 WebSocket）
    • 安全意识要贯穿始终：即使小型项目，也要做好基础安全防护

    项目已部署并稳定运行，包含了从开发到部署的完整流程。通过这个案例，我希望展示：

    • 如何用现代化技术栈快速构建全栈应用
    • 中小型项目的架构设计思路
    • Docker 容器化部署的实际操作

    这个项目还有很大的改进空间（如单元测试、性能监控、WebSocket 功能等），但作为一个可用系统的实现案例，希望能给其他开发者一些参考。如果你对项目有任何建议或想法，欢迎交流讨论！

    项目地址

    在线体验

    技术栈

    • 前端：Next.js 14 + React 18 + TypeScript 5 + Turborepo
    • 后端：FastAPI + Python 3.10 + Pydantic v2 + SQLAlchemy
    • 数据库：MySQL 8.0 + Redis
    • 部署：Vercel + Docker + Nginx

  • 从零到一：打造一个支持 RAG 的智能聊天应用

    在 AI 大模型快速发展的今天，如何构建一个既实用又具备先进功能的聊天应用成为了许多开发者关注的话题。本文将分享我从零开始构建一个集成了 RAG（检索增强生成）、多轮对话管理、本地向量存储 的现代化 AI 聊天应用的完整过程。(在线演示：Live Demo)

    ✨ 核心特性

    🤖 智能对话系统

    • 流式响应：基于 Vercel AI SDK 的实时流式对话
    • 多轮对话：完整的对话历史管理和上下文保持
    • 智能标题：基于对话内容自动生成对话标题
    • 数据持久化：页面刷新后对话历史不丢失

    📚 RAG 文档检索系统

    • 文档上传：支持 TXT、MD 格式文档
    • 智能分块：自动将长文档分割为语义块
    • 本地向量化：使用 @xenova/transformers 在客户端进行向量化
    • 语义搜索：基于余弦相似度的智能文档检索
    • 上下文增强：结合文档内容生成更准确的回复

    🎨 现代化 UI/UX

    • 响应式设计：完美适配桌面和移动设备
    • 主题切换：支持浅色/深色/跟随系统主题
    • 组件化架构：基于 Tailwind CSS 的设计系统
    • 流畅动画：优雅的交互体验

    🏗️ 技术架构

    前端技术栈

    Next.js 15 + React 19 + TypeScript
Tailwind CSS 4 + 响应式设计
Vercel AI SDK + 流式响应

    RAG 系统架构

    混合架构设计：
├── 客户端：文档处理 + 向量化 + 本地存储
└── 服务端：语义搜索 + 上下文生成

    核心技术选型

    • @xenova/transformers：客户端机器学习和向量化
    • localStorage：本地向量数据库存储
    • 余弦相似度：语义相似度计算
    • React Hooks：状态管理和逻辑复用

    🔧 核心实现

    1. 多轮对话管理

    // useMultiTurnChat Hook - 统一管理对话状态
export function useMultiTurnChat() {
  const [currentConversationId, setCurrentConversationId] = useState<string | null>(null)
  const [conversations, setConversations] = useState<Conversation[]>([])
  
  // 监听消息变化并自动保存
  useEffect(() => {
    if (!currentConversationId || messages.length === 0) return
    
    const formattedMessages = messages.map(msg => ({
      id: msg.id,
      role: msg.role as 'user' | 'assistant',
      content: msg.content,
      timestamp: new Date(),
      conversationId: currentConversationId
    }))
    
    conversationManager.updateConversation(currentConversationId, {
      messages: formattedMessages
    })
  }, [messages, currentConversationId])
  
  return {
    messages, conversations, currentConversation,
    createNewConversation, switchConversation, deleteConversation
  }
}

    2. RAG 文档处理流程

    // 文档处理 + 向量化
class DocumentProcessor {
  async processDocument(file: File): Promise<ProcessedDocument> {
    // 1. 读取文档内容
    const content = await this.readFileContent(file)
    
    // 2. 智能分块
    const chunks = await this.chunkText(content, {
      chunkSize: 500,
      chunkOverlap: 50
    })
    
    // 3. 向量化
    const embeddings = await this.generateEmbeddings(chunks)
    
    // 4. 存储到本地向量数据库
    await vectorStore.addDocument({
      id: generateId(),
      title: file.name,
      content,
      chunks: chunks.map((chunk, index) => ({
        id: generateId(),
        content: chunk,
        embedding: embeddings[index]
      }))
    })
    
    return processedDocument
  }
}

    3. 语义搜索实现

    // RAG 管理器 - 智能检索
class RAGManager {
  async generateChatContext(query: string, topK: number = 3): Promise<string> {
    // 1. 查询向量化
    const queryEmbedding = await this.generateEmbedding(query)
    
    // 2. 语义搜索
    const results = await this.vectorStore.search(queryEmbedding, topK)
    
    // 3. 生成上下文
    if (results.length === 0) return ''
    
    const context = results
      .map(result => `文档：${result.documentTitle}\n内容：${result.content}`)
      .join('\n\n')
    
    return `基于以下文档内容回答问题：\n\n${context}\n\n问题：${query}`
  }
}

    4. 本地向量存储

    // localStorage 向量数据库
class LocalStorageVectorStore implements VectorStore {
  async search(queryEmbedding: number[], topK: number): Promise<SearchResult[]> {
    const allChunks = this.getAllChunks()
    
    // 计算余弦相似度
    const similarities = allChunks.map(chunk => ({
      ...chunk,
      similarity: this.cosineSimilarity(queryEmbedding, chunk.embedding)
    }))
    
    // 排序并返回 topK 结果
    return similarities
      .sort((a, b) => b.similarity - a.similarity)
      .slice(0, topK)
      .filter(result => result.similarity > 0.5) // 相似度阈值
  }
  
  private cosineSimilarity(a: number[], b: number[]): number {
    const dotProduct = a.reduce((sum, val, i) => sum + val * b[i], 0)
    const magnitudeA = Math.sqrt(a.reduce((sum, val) => sum + val * val, 0))
    const magnitudeB = Math.sqrt(b.reduce((sum, val) => sum + val * val, 0))
    return dotProduct / (magnitudeA * magnitudeB)
  }
}

    🎨 UI/UX 设计亮点

    1. 对话侧边栏

    • 智能分组：按时间自动分组（今天、昨天、本周等）
    • 可折叠设计：节省屏幕空间
    • 悬浮操作：鼠标悬浮显示删除按钮

    2. RAG 管理面板

    • 文档拖拽上传：支持拖拽和点击上传
    • 实时搜索预览：输入查询时实时显示相关文档
    • 文档状态指示：清晰显示处理进度

    3. 响应式适配

    /* 移动端优化 */
@media (max-width: 768px) {
  .conversation-sidebar {
    position: fixed;
    transform: translateX(-100%);
    transition: transform 0.3s ease;
  }
  
  .conversation-sidebar.open {
    transform: translateX(0);
  }
}

    🚀 性能优化

    1. 客户端向量化

    • 优势：减少服务器负载，提高响应速度
    • 实现：使用 Web Workers 避免阻塞主线程
    • 缓存：向量结果本地缓存，避免重复计算

    2. 智能分块策略

    const chunkingStrategy = {
  chunkSize: 500,        // 块大小
  chunkOverlap: 50,      // 重叠部分
  preserveStructure: true // 保持文档结构
}

    3. 内存管理

    • 懒加载：按需加载向量数据
    • LRU 缓存：限制内存使用
    • 垃圾回收：及时清理无用数据

    🔍 技术难点与解决方案

    1. 页面刷新数据丢失

    问题：useChat hook 的状态在页面刷新后丢失

    解决方案：

    // 监听 messages 变化自动保存
useEffect(() => {
  if (!currentConversationId || messages.length === 0) return
  
  // 实时保存到 localStorage
  conversationManager.updateConversation(currentConversationId, {
    messages: formattedMessages
  })
}, [messages, currentConversationId])

    2. 向量相似度计算精度

    问题：余弦相似度计算结果不够准确

    解决方案：

    • 向量归一化处理
    • 动态相似度阈值
    • 多重排序策略

    3. 大文档处理性能

    问题：大文档分块和向量化耗时过长

    解决方案：

    // Web Worker 异步处理
const worker = new Worker('/workers/document-processor.js')
worker.postMessage({ content, chunkSize })
worker.onmessage = (event) => {
  const { chunks, embeddings } = event.data
  // 处理结果
}

    📊 项目成果

    功能完整性

    • ✅ 多轮对话管理
    • ✅ RAG 文档检索
    • ✅ 数据持久化
    • ✅ 响应式设计
    • ✅ 主题切换

    性能指标

    • 首屏加载：< 2s
    • 对话响应：< 500ms
    • 文档处理：< 3s (1MB 文档)
    • 搜索延迟：< 100ms

    代码质量

    • TypeScript 覆盖率：100%
    • 组件复用率：85%
    • 测试覆盖率：80%

    🎓 技术收获

    1. RAG 系统设计

    • 理解了检索增强生成的核心原理
    • 掌握了向量数据库的设计和实现
    • 学会了语义搜索的优化策略

    2. 前端架构设计

    • 组件化和模块化的最佳实践
    • 状态管理的复杂场景处理
    • 性能优化的系统性方法

    3. 用户体验设计

    • 响应式设计的细节处理
    • 交互动画的合理运用
    • 无障碍设计的重要性

    🔮 未来规划

    短期目标

    • 支持更多文档格式（PDF、DOCX）
    • 添加文档预览功能
    • 优化移动端体验

    长期目标

    • 支持多模态输入（图片、音频）
    • 集成更多 AI 模型
    • 添加协作功能

    📝 总结

    这个项目让我深入理解了现代 AI 应用的完整开发流程，从前端 UI/UX 设计到后端 RAG 系统实现，从性能优化到用户体验，每个环节都有很多值得深入探索的技术点。

    特别是 RAG 系统的实现，让我对向量数据库、语义搜索、上下文生成等技术有了更深入的理解。同时，通过解决页面刷新数据丢失、向量相似度计算等技术难点，也积累了宝贵的实战经验。

    希望这个项目能够为正在学习 AI 应用开发的同学提供一些参考和启发。完整的源码已经开源，欢迎大家交流讨论！

    🔗 相关链接

    如果这篇文章对你有帮助，欢迎点赞、收藏和分享！有任何问题也欢迎在评论区讨论。

  • NSGM CLI

    一个具有代码模板生成能力的全栈开发框架，帮助开发者高效构建Web应用。

    开源情况

    NSGM CLI 是一个活跃维护的开源项目，欢迎社区贡献和使用：

    快速安装

    # 全局安装
npm install -g nsgm-cli

# 或作为项目依赖安装
npm install --save nsgm-cli

    为什么选择NSGM CLI？

    • 开箱即用：集成了现代Web开发所需的所有核心功能
    • 开发效率：通过代码模板生成大幅提高开发速度
    • 全栈解决方案：前后端一体化设计，无缝衔接
    • 活跃维护：定期更新和bug修复，确保框架稳定性
    • 社区支持：开源社区持续贡献和改进

    技术栈

    特性

    • 全栈架构设计
    • 自动代码模板生成
    • 快速开发工作流
    • 集成GraphQL API
    • MySQL数据库支持
    • 使用bcrypt加密的安全登录系统
    • 完整的项目脚手架
    • 开发与生产环境配置
    • 自动化部署支持

    适用场景

    • 企业级Web应用开发
    • 个人项目快速原型设计
    • 全栈开发学习与教学
    • 需要高效开发流程的团队
    • 需要统一技术栈的中大型项目

    命令行工具

    基本命令

    命令 描述
    nsgm init 初始化项目
    nsgm upgrade 升级项目基础文件
    nsgm create 创建模板页面
    nsgm delete 删除模板页面
    nsgm deletedb 删除模板页面和数据库表
    nsgm dev 开发模式
    nsgm start 生产模式
    nsgm build 构建项目
    nsgm export 导出静态页面

    参数说明

    • dictionary: 与export/init命令一起使用，默认值为webapp

      nsgm init dictionary=webapp
# 或简化为
nsgm init webapp

    • controller: 与create/delete命令一起使用，必需参数

      nsgm create math

    • action: 与create/delete命令一起使用，默认值为manage，跟在controller后面

      nsgm create math test

    开发流程示例

    1. 创建新项目

    # 安装CLI工具
npm install -g nsgm-cli

# 初始化新项目
nsgm init myproject

# 进入项目目录
cd myproject

# 安装依赖
npm install

    2. 创建功能模块

    # 创建用户管理模块
nsgm create user

# 创建带自定义操作的产品模块
nsgm create product detail

    3. 启动开发服务器

    # 启动开发模式
nsgm dev

    快速设置

    1. 生成密码哈希：

      # 使用npm脚本
npm run generate-password yourSecurePassword

    2. 创建.env文件：

      LOGIN_USERNAME=admin
LOGIN_PASSWORD_HASH=your_generated_hash_here

    3. 确保.env在你的.gitignore文件中。

    ⚠️ 重要提示： 永远不要将密码或.env文件提交到版本控制系统。

    项目配置

    next.config.js

    const { nextConfig } = require('nsgm-cli')
const projectConfig = require('./project.config')

const { version, prefix, protocol, host } = projectConfig

module.exports = (phase, defaultConfig) => {
  let configObj = nextConfig(phase, defaultConfig, {
    version,
    prefix,
    protocol,
    host
  })

  return configObj
}

    mysql.config.js

    const { mysqlConfig } = require('nsgm-cli')
const { mysqlOptions } = mysqlConfig
const { user, password, host, port, database } = mysqlOptions

module.exports = {
  mysqlOptions: {
    user,
    password,
    host,
    port,
    database
  }
}

    project.config.js

    const { projectConfig } = require('nsgm-cli')
const pkg = require('./package.json')

const { prefix, protocol, host, port } = projectConfig
const { version } = pkg

module.exports = {
  version,
  prefix,
  protocol,
  host,
  port
}

    服务器目录结构

    项目根目录中的server文件夹包含以下内容：

    目录说明

    • apis/ – 存储REST API接口
    • modules/ – 存储GraphQL解析器和模式
    • plugins/ – 存储GraphQL插件
    • *.js – 路由文件

    示例代码

    路由文件示例 (server/rest.js)

    const express = require('express')
const moment = require('moment')

const router = express.Router()

router.use((req, res, next) => {
  const fullUrl = req.protocol + '://' + req.get('host') + req.originalUrl
  console.log(moment().format('YYYY-MM-DD HH:mm:ss') + ' ' + fullUrl)
  next()
})

router.get('/*', (req, res) => {
  res.statusCode = 200
  res.json({ name: 'TEST' })
})

module.exports = router

    REST API示例 (server/apis/hello.js)

    const express = require('express')
const router = express.Router()

router.get('/*', (req, res) => {
  res.statusCode = 200
  res.json({ name: 'Hello' })
})

module.exports = router

    GraphQL模式示例 (server/modules/link/schema.js)

    module.exports = {
  query: `
        link: String
    `,
  mutation: `
        linkUpdate(link: Date): String
    `,
  subscription: ``,
  type: ``
}

    GraphQL解析器示例 (server/modules/link/resolver.js)

    let localLink = ''

module.exports = {
  link: () => {
    return localLink
  },
  linkUpdate: ({ link }) => {
    console.log('link', link)
    localLink = link
    return localLink
  }
}

    GraphQL插件示例 (server/plugins/date.js)

    const moment = require('moment')
const { Kind } = require('graphql/language')
const { GraphQLScalarType } = require('graphql')

const customScalarDate = new GraphQLScalarType({
  name: 'Date',
  description: 'Date custom scalar type',
  parseValue: (value) => moment(value).valueOf(),
  serialize: (value) => moment(value).format('YYYY-MM-DD HH:mm:ss:SSS'),
  parseLiteral: (ast) => (ast.kind === Kind.INT ? parseInt(ast.value, 10) : null)
})

module.exports = { Date: customScalarDate }

    社区与支持

    • 问题反馈：如果您在使用过程中遇到任何问题，请在GitHub Issues提交
    • 功能请求：有新功能建议？欢迎在Issues中提出
    • 贡献代码：我们欢迎Pull Requests，请确保遵循项目的代码规范
    • 联系作者：有任何问题可以通过GitHub联系项目维护者

    成功案例

    NSGM CLI已被用于多个成功的Web应用项目：

    • 企业内部管理系统
    • 数据可视化平台
    • 电子商务网站
    • 个人博客系统
    • 教育培训平台

    未来规划

    我们正在积极开发以下功能：

    • 更多数据库支持（MongoDB, PostgreSQL）
    • 容器化部署支持
    • 更丰富的UI组件库
    • 微服务架构支持
    • 更完善的文档和教程

    NSGM CLI – 让全栈开发更简单、更高效

  • 用一副三角尺能画出145度的角吗？说明理由

    仅使用一副标准的三角尺（30°-60°-90° 和 45°-45°-90°），无法直接画出145度的角，因为三角尺提供的角度无法组合或分解成145度。

    原因分析：

    1. 三角尺提供的角度：

      • 30°-60°-90°三角尺：可提供 30°、60° 和 90°。
      • 45°-45°-90°三角尺：可提供 45° 和 90°。
      • 它们组合后，可以画出的角包括：15°、30°、45°、60°、75°、90°、105°、120°、135°、150° 等。

    2. 无法组合145°：

      • 145° 是一个钝角，但无法用这些已知角度的加法或减法准确表示。例如，145° ≠ 135° + 10°（无法精确分解出10°）。

    结论：

    因此，用一副标准的三角尺无法直接画出145°的角。如果需要145°的角，可以借助量角器或者其他工具进行精确绘制。

  • 使用 styled-components 实现带有动态秒针的圆盘时钟的示例

    import React, { useState, useEffect } from 'react';
import styled from 'styled-components';

const ClockContainer = styled.div`
  width: 200px;
  height: 200px;
  border: 8px solid #333;
  border-radius: 50%;
  position: relative;
  display: flex;
  align-items: center;
  justify-content: center;
  background-color: white;
`;

const Hand = styled.div`
  position: absolute;
  bottom: 50%;
  left: 50%;
  background: #333;
  transform-origin: bottom;
  transition: transform 0.5s ease-in-out;

  &.hour {
    height: 50px;
    width: 6px;
    background: black;
  }

  &.minute {
    height: 70px;
    width: 4px;
    background: gray;
  }

  &.second {
    height: 90px;
    width: 2px;
    background: red;
  }
`;

const Center = styled.div`
  position: absolute;
  width: 14px;
  height: 14px;
  background: black;
  border-radius: 50%;
`;

const Number = styled.div`
  position: absolute;
  font-size: 16px;
  font-weight: bold;
  color: black;
`;

const Clock = () => {
  const [secondCounts, setSecondCounts] = useState(0);
  const [minuteCounts, setMinuteCounts] = useState(0);
  const [hourCounts, setHourCounts] = useState(0);
  const [time, setTime] = useState(new Date());

  useEffect(() => {
    const interval = setInterval(() => {
      setTime(new Date());
    }, 1000);

    return () => clearInterval(interval);
  }, []);

  const formatTime = (date) => {
    const hours = date.getHours() % 12;
    const minutes = date.getMinutes();
    const seconds = date.getSeconds();
    return { hours, minutes, seconds };
  };

  const { hours, minutes, seconds } = formatTime(time);

  useEffect(() => {
    if(seconds === 0){
      setSecondCounts((secondCounts)=> secondCounts + 1);
    }

    if(minutes === 0 && seconds === 0){
      setMinuteCounts((minuteCounts)=> minuteCounts + 1);
    }

    if(hourCounts === 0 && minutes === 0 && seconds === 0){
      setHourCounts((hourCounts)=> hourCounts + 1);
    }
  }, [hours, minutes, seconds]);

  const renderNumbers = () => {
    const numbers = Array.from({ length: 12 }, (_, index) => index + 1);
    return numbers.map((number) => {
      const angle = (number * 30) - 90; // 计算数字位置
      const x = 80 * Math.cos((angle * Math.PI) / 180);
      const y = 80 * Math.sin((angle * Math.PI) / 180);
      return (
        <Number key={number} style={{ transform: `translate(${x}px, ${y}px)` }}>
          {number}
        </Number>
      );
    });
  };

  return (
    <ClockContainer>
      {renderNumbers()}
      <Hand className="hour" style={{ transform: `rotate(${(hours * 30) + (minutes / 2) + hourCounts * 360}deg)` }} />
      <Hand className="minute" style={{ transform: `rotate(${minutes * 6 + minuteCounts * 360}deg)` }} />
      <Hand className="second" style={{ transform: `rotate(${seconds * 6 + secondCounts * 360}deg)` }} />
      <Center />
    </ClockContainer>
  );
};

export default Clock;

  • 数学 – 分数的加减法

    描述文本

    这个流程图描述了一个简单的数学计算过程。

    1. 开始：开始节点。
    2. 输入：输入两个数（1/5 和 1/3）。
    3. 相加：计算这两个数的和。
    4. 判断：判断和是否大于 3。
      • 如果是：
        • 减去 3/4：从和中减去 3/4。
        • 输出结果：输出结果。
      • 如果否：
        • 输出结果：直接输出和。
    5. 结束：结束节点。

    代码

    const Fraction = require('fraction.js');

function calculateAndAdjust(num1, num2) {
  const sum = new Fraction(num1).add(new Fraction(num2));
  if (sum.compare(3) > 0) {
    return sum.sub(new Fraction(3, 4));
  }
  return sum;
}

// 示例调用
const result = calculateAndAdjust(1 / 5, 1 / 3);
console.log(result.toFraction());

    结果

    8/15

    解释

    这个代码片段使用了 fraction.js 库来处理分数运算。首先，它将输入的两个数转换为分数，然后计算它们的和。如果和大于 3，则从和中减去 3/4。最后，输出结果。

    注意

    • 请确保在运行代码之前安装了 fraction.js 库。
    • 这个代码片段假设输入的数是有效的，没有进行错误处理。在实际应用中，可能需要添加错误处理逻辑。

  • Mac Brew Mysql Issue

    • ERROR 1524 (HY000): Plugin 'mysql_native_password' is not loaded

    https://github.com/Homebrew/homebrew-core/issues/180498

    MySQL 9 不再支持 mysql_native_password 认证方法，这可能会影响从 MySQL 8.x 升级到 MySQL 9 的用户。为了解决此问题，您需要更新 MySQL 用户表，使用新的认证方法。按照以下步骤操作：

    1.- 禁用权限表：
    编辑 MySQL 配置文件，通常位于 /opt/homebrew/etc/my.cnf。在 [mysqld] 部分下添加以下行以禁用权限表：

    [mysqld]
skip-grant-tables

    2.- 重启 MySQL：
    使用 Homebrew 重启 MySQL：

    brew services restart mysql

    3.- 以 root 用户连接 MySQL：

    mysql -uroot

    4.- 更新用户认证方法：
    刷新权限：

    FLUSH PRIVILEGES;

    5.- 检查使用 mysql_native_password 插件的用户：

    SELECT User, Host, plugin FROM mysql.user WHERE plugin = 'mysql_native_password';

    6.- 将 root 用户更新为使用 caching_sha2_password 插件：

    ALTER USER 'root'@'localhost' IDENTIFIED WITH caching_sha2_password BY 'new_password';

    7.- 重新启用权限表：
    更新后，删除或注释掉 MySQL 配置文件中的 skip-grant-tables 行。

    8.- 重启 MySQL 以应用更改：

    brew services restart mysql

    通过执行这些步骤，您应该能够在升级到 MySQL 9 后解决认证方法问题。

    • err_mysqlConnect: Error: ER_NOT_SUPPORTED_AUTH_MODE: Client does not support authentication protocol requested by server; consider upgrading MySQL client

    https://stackoverflow.com/questions/50093144/mysql-8-0-client-does-not-support-authentication-protocol-requested-by-server

    使用 npm 安装 mysql2：
    https://github.com/sidorares/node-mysql2

  • 如何设置 Node、TypeScript 和 Express

    TypeScript 是 JavaScript 的超集，提供了强类型支持，让开发者可以编写更安全、更健壮的代码。在本文中，我们将探讨如何将 TypeScript 与 Node.js 和 Express 一起使用，并构建一个简单的应用程序。

    原文链接

    前提条件

    要完成本教程，你需要以下工具：

    • 安装了 Node.js（建议使用 v16 或更高版本）
    • 基本的 JavaScript 和 Node.js 知识

    第一步：初始化项目

    首先，我们需要创建一个新目录并初始化一个新的 Node.js 项目。在终端中运行以下命令：

    mkdir node-ts-express
cd node-ts-express
npm init -y

    这将创建一个新的 package.json 文件，默认设置所有值。接下来，我们将安装 TypeScript 和一些必要的依赖项。

    第二步：安装 TypeScript 及其他依赖项

    为了使用 TypeScript，我们需要安装 TypeScript 编译器和 Node.js 的类型定义：

    npm install typescript ts-node @types/node --save-dev
    • typescript 是 TypeScript 编译器
    • ts-node 允许我们在 Node.js 中直接运行 TypeScript 文件，而无需手动编译
    • @types/node 包含 Node.js API 的类型定义

    接下来，我们还需要安装 Express 和其类型定义：

    npm install express
npm install @types/express --save-dev

    第三步：配置 TypeScript

    接下来，我们将设置 TypeScript 配置文件 tsconfig.json。在项目根目录下运行以下命令：

    npx tsc --init

    这个命令将在项目根目录中生成一个 tsconfig.json 文件。打开这个文件，确保以下选项被正确设置：

    {
  "compilerOptions": {
    "target": "ES6",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  }
}
    • target 设置了编译后的 JavaScript 版本（在本例中为 ES6）
    • module 指定模块系统（在本例中为 CommonJS）
    • outDir 指定编译后文件的输出目录
    • rootDir 定义 TypeScript 源文件所在的目录
    • strict 启用严格的类型检查选项
    • esModuleInterop 允许兼容 CommonJS 和 ES 模块

    第四步：创建 Express 服务器

    现在，我们可以开始编写代码了。首先，创建一个 src 目录，并在其中创建一个名为 index.ts 的文件：

    mkdir src
touch src/index.ts

    在 index.ts 文件中，添加以下代码：

    import express, { Request, Response } from 'express';

const app = express();
const PORT = 3000;

app.get('/', (req: Request, res: Response) => {
  res.send('Hello, TypeScript with Node.js!');
});

app.listen(PORT, () => {
  console.log(`Server is running at http://localhost:${PORT}`);
});

    在这段代码中，我们导入了 Express 和类型定义，并创建了一个基本的 Express 服务器。服务器监听 3000 端口，并在根路由 / 返回一个简单的消息。

    第五步：运行 TypeScript 应用程序

    为了运行这个 TypeScript 应用程序，我们可以使用 ts-node 命令。运行以下命令：

    npx ts-node src/index.ts

    这将启动服务器，你可以在浏览器中访问 http://localhost:3000，并看到页面显示 "Hello, TypeScript with Node.js!"。

    第六步：编译 TypeScript 代码

    尽管 ts-node 非常方便，但在生产环境中，你通常会编译 TypeScript 代码为 JavaScript，然后运行编译后的代码。要编译 TypeScript 代码，运行以下命令：

    npx tsc

    这将编译 src 目录中的所有 TypeScript 文件，并将编译后的 JavaScript 文件输出到 dist 目录中。你可以通过以下命令运行编译后的应用程序：

    node dist/index.js

    总结

    在本文中，我们介绍了如何在 Node.js 项目中设置 TypeScript，并使用 Express 创建了一个简单的服务器。TypeScript 提供的强类型检查和其他特性，使得它成为构建更大规模、复杂应用程序的理想选择。

    你可以根据项目需求扩展此设置，添加更多的中间件、路由、控制器等。希望你在使用 TypeScript 构建 Node.js 应用时取得成功！