# next-base

**Repository Path**: QOH/next-base

## Basic Information

- **Project Name**: next-base
- **Description**: 这是一个基于 Next.js 15 + React 19 + TypeScript + Tailwind CSS + shadcn/ui 的现代化 Web 应用基础项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-09-02
- **Last Updated**: 2025-11-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Next.js CSGO 项目

这是一个基于 Next.js 15 + React 19 + TypeScript + Tailwind CSS + shadcn/ui 的现代化 Web 应用项目。

## 技术栈

- **框架**: Next.js 15 (App Router)
- **UI库**: React 19
- **类型系统**: TypeScript 5
- **样式**: Tailwind CSS 4
- **组件库**: shadcn/ui
- **状态管理**: Redux Toolkit
- **HTTP 请求**: Axios + 统一封装 + SWR 数据获取
- **国际化**: next-intl
- **字体**: Geist Sans & Geist Mono
- **包管理器**: pnpm
- **构建工具**: Turbopack

## 快速开始

### 安装依赖

```bash
pnpm install
```

### 启动开发服务器

```bash
pnpm dev
```

打开 [http://localhost:3000](http://localhost:3000) 查看应用。

### 构建生产版本

```bash
pnpm build
pnpm start
```

## 国际化支持

本项目支持多语言国际化，目前支持：
- 🇨🇳 中文（默认）
- 🇺🇸 English
- 🇯🇵 日本語

### 国际化特性

- **自动语言检测**：根据浏览器语言自动选择
- **URL 路由**：支持 `/zh`、`/en`、`/ja` 路径
- **语言切换**：右上角语言切换器
- **静态生成**：所有语言版本都支持静态生成
- **类型安全**：完整的 TypeScript 类型支持

### 添加新语言

1. 在 `messages/` 目录下创建新的语言文件（如 `fr.json`）
2. 在 `src/i18n/routing.ts` 中添加新的语言代码
3. 在 `src/components/LanguageSwitcher.tsx` 中添加语言选项

### 使用翻译

```tsx
// 服务端组件
import { getTranslations } from 'next-intl/server';

export default async function Page() {
  const t = await getTranslations();
  return <h1>{t('home.title')}</h1>;
}

// 客户端组件
'use client';
import { useTranslations } from 'next-intl';

export default function Component() {
  const t = useTranslations();
  return <p>{t('common.loading')}</p>;
}
```

## Redux Toolkit 状态管理

本项目集成了 Redux Toolkit 进行全局状态管理，提供了现代化的 Redux 开发体验。

### Redux 特性

- **Redux Toolkit**：使用官方推荐的现代 Redux 工具集
- **类型安全**：完整的 TypeScript 类型支持
- **DevTools**：集成 Redux DevTools 用于调试
- **异步处理**：使用 createAsyncThunk 处理异步操作
- **Immer 集成**：支持不可变状态的直接修改语法

### Store 结构

```typescript
// src/lib/store.ts
export const store = configureStore({
  reducer: {
    counter: counterReducer,    // 计数器状态
    user: userReducer,         // 用户管理状态
  },
});
```

### 使用示例

```typescript
// 使用类型化的 hooks
import { useAppDispatch, useAppSelector } from '@/lib/hooks';
import { increment, decrement } from '@/lib/features/counter/counterSlice';

function Counter() {
  const dispatch = useAppDispatch();
  const count = useAppSelector((state) => state.counter.value);
  
  return (
    <div>
      <span>{count}</span>
      <button onClick={() => dispatch(increment())}>+</button>
      <button onClick={() => dispatch(decrement())}>-</button>
    </div>
  );
}
```

### 服务端数据预填充（深层合并）

```typescript
// 在页面组件中
const users = await fetchUsersOnServer();

// 只需传入需要预填充的部分，其他字段会自动使用默认值
const preloadedState = {
  user: {
    users: users, // 只传入需要的数据
  }
};

// 传递给 StoreProvider，会自动深层合并
return (
  <StoreProvider preloadedState={preloadedState}>
    {children}
  </StoreProvider>
);
```

### 已实现的功能

1. **计数器演示**：
   - 基本的增减操作
   - 自定义步长设置
   - 自定义增量输入
   - 重置功能

2. **用户管理演示**：
   - 服务端预渲染用户列表
   - 用户登录/登出
   - 添加/删除用户
   - 状态管理和错误处理

## HTTP 请求封装

本项目集成了基于 axios 的请求封装，参照 vebn-admin 风格：

### 特性

- **统一拦截器**：请求/响应统一处理
- **Cookie Token 管理**：Token 存储在 Cookie 中，支持访问令牌和刷新令牌
- **QS 参数处理**：使用 qs 库处理复杂参数序列化
- **错误统一处理**：全局错误拦截和提示
- **TypeScript 支持**：完整的类型定义
- **多种请求方法**：GET、POST、PUT、DELETE、PATCH 等

### 使用方法

#### 1. 基础请求

```typescript
import request from '@/lib/request';

// GET 请求
const response = await request.get('/api/users');

// POST 请求
const response = await request.post('/api/users', { name: 'John' });

// 文件上传
const response = await request.upload('/api/upload', formData);
```

#### 2. API 服务层

```typescript
import request, { ResultData } from '@/lib/request';

export const getUserList = (params?: any): Promise<ResultData<User[]>> => {
  return request.get('/users', params);
};

export const createUser = (params: CreateUserParams): Promise<ResultData<User>> => {
  return request.post('/users', params);
};
```

#### 3. Token 管理

```typescript
import request from '@/lib/request';
import { TokenManager } from '@/lib/utils/token';

// 设置令牌
request.setToken('your-access-token');
TokenManager.setToken('your-access-token');

// 设置令牌对
request.setTokens('access-token', 'refresh-token');

// 获取令牌
const token = request.getTokenPublic();
const hasToken = request.hasToken();

// 清除令牌
request.clearToken();
```

#### 4. 参数处理

```typescript
// 复杂参数会自动使用 qs 序列化
const response = await request.get('/api/users', {
  filters: {
    status: ['active', 'pending'],
    roles: ['admin', 'user']
  },
  pagination: {
    page: 1,
    limit: 10
  }
});
// 生成: /api/users?filters[status][0]=active&filters[status][1]=pending...
```

#### 5. 环境变量配置

创建 `.env.local` 文件：
```env
# API 配置
NEXT_PUBLIC_API_BASE_URL=http://localhost:3000/api

# WebSocket 配置
NEXT_PUBLIC_WS_BASE_URL=ws://localhost:8080
NEXT_PUBLIC_WS_CHAT_URL=ws://localhost:8080/chat
NEXT_PUBLIC_WS_NOTIFICATION_URL=ws://localhost:8080/notifications
```

### API 结构

```
src/lib/
├── request/
│   └── index.ts       # HTTP 请求封装
├── api/
│   ├── index.ts       # API 统一导出
│   └── user.ts        # 用户相关 API
├── swr/
│   └── config.ts      # SWR 配置
├── hooks/
│   ├── useSWR.ts      # SWR hooks 工具
│   ├── useWebSocket.ts # WebSocket hooks
│   └── useSharedWebSocket.ts # 共享 WebSocket hooks
├── utils/
│   ├── errorHandler.ts # 错误处理工具
│   ├── token.ts        # Token 管理工具
│   └── toast.ts        # Toast 通知工具
├── websocket/
│   ├── WebSocketManager.ts # WebSocket 管理器
│   └── index.ts        # WebSocket 工厂
└── serverActions.ts   # 服务端数据获取
```

## Sonner Toast 通知

项目集成了 Sonner 作为现代化的 Toast 通知系统：

### 特性

- **现代化设计**：支持深色模式和丰富的视觉效果
- **多种类型**：成功、错误、警告、信息、加载状态
- **Promise 支持**：自动处理异步操作状态
- **操作按钮**：支持操作和取消按钮
- **自定义样式**：支持完全自定义的通知内容
- **智能管理**：自动堆叠、展开和过期处理

### 使用方法

```typescript
import { toast } from '@/lib/utils/toast';

// 基础通知
toast.success('操作成功');
toast.error('操作失败');
toast.warning('警告信息');
toast.info('提示信息');

// Promise 通知
toast.promise(apiCall(), {
  loading: '处理中...',
  success: '操作成功',
  error: '操作失败',
});

// 操作通知
toast.action('文件已删除', '撤销', () => {
  // 撤销操作
});

// 自定义通知
toast.custom(
  <div>自定义内容</div>,
  { duration: 5000 }
);
```

## WebSocket 实时通信

项目提供了完整的 WebSocket 封装，支持实时通信：

### 特性

- **连接管理**：自动连接、重连、心跳保活
- **连接复用**：相同 URL 自动复用连接，引用计数管理
- **消息处理**：类型化消息、事件订阅、消息队列
- **React 集成**：多种专用 Hook，状态自动管理
- **跨页面共享**：支持跨页面、跨组件的连接复用
- **Token 集成**：自动注入认证信息
- **错误处理**：完善的错误处理和重试机制

### 使用方法

#### 基础 WebSocket

```typescript
import { useWebSocket } from '@/lib/hooks/useWebSocket';

function MyComponent() {
  const { send, isConnected, state } = useWebSocket('ws://localhost:8080', {
    onOpen: () => console.log('连接成功'),
    onMessage: (data) => console.log('收到消息:', data),
  });

  const sendMessage = () => {
    send({ type: 'message', data: 'Hello' });
  };
}
```

#### 聊天 WebSocket

```typescript
import { useWebSocketChat } from '@/lib/hooks/useWebSocket';

function ChatComponent() {
  const { messages, sendMessage, isConnected } = useWebSocketChat('ws://localhost:8080/chat');

  return (
    <div>
      {messages.map(msg => (
        <div key={msg.id}>{msg.content}</div>
      ))}
      <button onClick={() => sendMessage('Hello!')}>
        发送消息
      </button>
    </div>
  );
}
```

#### WebSocket 工厂

```typescript
import WebSocketFactory from '@/lib/websocket';

// 获取聊天实例
const chatWs = WebSocketFactory.getChat();

// 获取通知实例
const notificationWs = WebSocketFactory.getNotification();

// 自定义实例
const customWs = WebSocketFactory.getCustom('myService', 'ws://example.com');
```

#### 连接复用 Hook

```typescript
import { useSharedWebSocket } from '@/lib/hooks/useSharedWebSocket';

function ComponentA() {
  // 多个组件使用相同 URL 会共享连接
  const ws = useSharedWebSocket('ws://localhost:8080/chat', {
    instanceKey: 'shared_chat', // 自定义实例键名
    onMessage: (data) => console.log('A 收到:', data),
  });
}

function ComponentB() {
  // 与 ComponentA 共享同一个连接
  const ws = useSharedWebSocket('ws://localhost:8080/chat', {
    instanceKey: 'shared_chat',
    onMessage: (data) => console.log('B 收到:', data),
  });
}
```

#### 预定义共享 Hook

```typescript
import { 
  useSharedChatWebSocket,
  useSharedNotificationWebSocket,
  useSharedGeneralWebSocket 
} from '@/lib/hooks/useSharedWebSocket';

// 聊天连接（跨组件共享）
const chat = useSharedChatWebSocket({
  onMessage: (data) => console.log('聊天消息:', data),
});

// 通知连接（跨组件共享）
const notification = useSharedNotificationWebSocket({
  onMessage: (data) => console.log('通知:', data),
});
```

## SWR 数据获取

本项目集成了 SWR 用于客户端数据获取和缓存：

### 特性

- **自动缓存**：智能缓存和重新验证
- **错误重试**：自动错误重试机制
- **乐观更新**：提升用户体验
- **错误拦截配置**：可配置是否拦截错误
- **国际化错误信息**：多语言错误提示
- **TypeScript 支持**：完整的类型安全

### 使用方法

#### 1. 基础数据获取

```typescript
import { useRequest } from '@/lib/hooks/useSWR';

function UserList() {
  const { data, error, isLoading } = useRequest<User[]>('/api/users');
  
  if (error) return <div>加载失败</div>;
  if (isLoading) return <div>加载中...</div>;
  return <div>{data?.map(user => user.name)}</div>;
}
```

#### 2. 数据变更操作

```typescript
import { usePostMutation } from '@/lib/hooks/useSWR';

function CreateUser() {
  const { trigger, isMutating } = usePostMutation('/api/users', {
    onSuccess: () => {
      // 成功后刷新列表
      mutate('/api/users');
    }
  });
  
  const handleCreate = () => {
    trigger({ name: 'New User', email: 'user@example.com' });
  };
  
  return (
    <button onClick={handleCreate} disabled={isMutating}>
      {isMutating ? '创建中...' : '创建用户'}
    </button>
  );
}
```

#### 3. 错误处理配置

```typescript
// 跳过错误拦截
const { data } = useRequest('/api/users', { 
  skipErrorHandler: true 
});

// 使用静默 fetcher
import { silentFetcher } from '@/lib/swr/config';
const { data } = useSWR('/api/users', silentFetcher);
```

## shadcn/ui 集成

本项目已完整集成 shadcn/ui 组件库，包含以下配置：

### 1. 核心依赖

```json
{
  "dependencies": {
    "class-variance-authority": "^0.7.0",
    "clsx": "^2.0.0",
    "tailwind-merge": "^2.0.0",
    "lucide-react": "^0.294.0"
  },
  "devDependencies": {
    "tailwindcss-animate": "^1.0.7"
  }
}
```

### 2. 配置文件

- `components.json` - shadcn/ui 配置文件
- `tailwind.config.ts` - Tailwind CSS 配置，包含 shadcn/ui 主题
- `src/app/globals.css` - 全局样式，包含 CSS 变量和暗色模式支持
- `src/lib/utils.ts` - 工具函数，包含 `cn` 函数用于样式合并

### 3. 已安装的组件

- Button - 按钮组件
- Card - 卡片组件
- Input - 输入框组件
- Label - 标签组件
- DropdownMenu - 下拉菜单组件
- Badge - 徽章组件

### 4. 添加新组件

使用 shadcn/ui CLI 添加新组件：

```bash
# 添加单个组件
pnpm dlx shadcn@latest add [component-name]

# 添加多个组件
pnpm dlx shadcn@latest add [component1] [component2] [component3]

# 查看可用组件
pnpm dlx shadcn@latest add
```

### 5. 使用示例

```tsx
import { Button } from "@/components/ui/button";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";

export default function MyComponent() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>示例卡片</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>点击我</Button>
      </CardContent>
    </Card>
  );
}
```

## 项目结构

```
src/
├── app/                 # Next.js App Router 页面
│   ├── [locale]/       # 国际化路由
│   │   ├── layout.tsx  # 语言布局
│   │   └── page.tsx    # 首页
│   ├── globals.css     # 全局样式
│   └── layout.tsx      # 根布局
├── components/         # 组件目录
│   ├── ui/            # shadcn/ui 组件
│   ├── providers/     # 上下文提供者
│   │   ├── SWRProvider.tsx # SWR 提供者
│   │   └── StoreProvider.tsx # Redux 提供者
│   ├── CounterDemo.tsx # 计数器演示组件
│   ├── UserDemo.tsx   # 用户管理演示组件
│   ├── UserSWRDemo.tsx # SWR 用户管理演示
│   ├── TokenDemo.tsx  # Token 管理演示
│   ├── SonnerDemo.tsx # Toast 通知演示
│   ├── WebSocketDemo.tsx # WebSocket 演示
│   ├── SharedWebSocketDemo.tsx # 共享 WebSocket 演示
│   └── LanguageSwitcher.tsx # 语言切换器
├── i18n/              # 国际化配置
│   ├── request.ts     # 请求配置
│   └── routing.ts     # 路由配置
├── lib/               # 工具库
│   ├── features/      # Redux 功能模块
│   │   ├── counter/   # 计数器状态
│   │   └── user/      # 用户状态
│   ├── request/       # HTTP 请求封装
│   │   └── index.ts   # Axios 请求工具
│   ├── api/           # API 服务层
│   │   ├── index.ts   # API 统一导出
│   │   └── user.ts    # 用户相关 API
│   ├── swr/           # SWR 配置
│   │   └── config.ts  # SWR 配置和 fetcher
│   ├── hooks/         # 自定义 hooks
│   │   ├── useSWR.ts  # SWR hooks 工具
│   │   └── index.ts   # Redux hooks
│   ├── utils/         # 工具函数
│   │   └── errorHandler.ts # 错误处理工具
│   ├── store.ts       # Redux store 配置
│   ├── storeUtils.ts  # Store 工具函数
│   ├── serverActions.ts # 服务端数据获取
│   └── utils.ts       # 通用工具函数
├── middleware.ts      # 中间件（处理语言路由）
└── messages/          # 语言文件
    ├── zh.json        # 中文翻译
    ├── en.json        # 英文翻译
    └── ja.json        # 日文翻译
```

## 特性

- ✅ **现代化技术栈**: Next.js 15 + React 19 + TypeScript
- ✅ **状态管理**: Redux Toolkit 全局状态管理 + 深层合并预填充
- ✅ **HTTP 请求**: Axios 统一封装 + SWR 数据获取 + 类型安全 API
- ✅ **国际化支持**: 多语言支持（中文/英文/日文）
- ✅ **响应式设计**: 基于 Tailwind CSS 的响应式布局
- ✅ **暗色模式**: 内置暗色模式支持
- ✅ **类型安全**: 完整的 TypeScript 类型定义
- ✅ **组件库**: 基于 shadcn/ui 的现代化组件
- ✅ **性能优化**: Turbopack 构建工具
- ✅ **可访问性**: 基于 Radix UI 的无障碍支持
- ✅ **静态生成**: 支持多语言静态站点生成
- ✅ **开发工具**: Redux DevTools 集成

## 开发指南

### 代码规范

- 使用 TypeScript 严格模式
- 遵循 ESLint 和 Prettier 配置
- 使用函数式组件和 React Hooks
- 优先使用 React Server Components

### 样式规范

- 使用 Tailwind CSS utility classes
- 通过 CSS 变量支持主题定制
- 使用 `cn()` 函数合并样式类

### 组件开发

- 组件放置在 `src/components/` 目录
- UI 组件使用 shadcn/ui
- 自定义组件遵循 shadcn/ui 设计规范

## 了解更多

- [Next.js 文档](https://nextjs.org/docs)
- [shadcn/ui 文档](https://ui.shadcn.com)
- [Tailwind CSS 文档](https://tailwindcss.com/docs)
- [TypeScript 文档](https://www.typescriptlang.org/docs)

## 部署

推荐使用 [Vercel](https://vercel.com) 部署，它是 Next.js 的创建者提供的平台。

查看 [Next.js 部署文档](https://nextjs.org/docs/app/building-your-application/deploying) 了解更多部署选项。