# next-fullstack-notes

**Repository Path**: andoridityu/next-fullstack-notes

## Basic Information

- **Project Name**: next-fullstack-notes
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-23
- **Last Updated**: 2025-09-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Next.js 全栈笔记应用

这是一个全栈 Next.js 应用程序，展示了使用最新 Next.js 特性的现代 Web 开发实践，包括 App Router、服务端渲染和静态站点生成。

## 技术栈 (Technology Stack)

### 核心框架 (Core Framework)
- **Next.js 15** - React 全栈框架，支持服务端渲染和静态生成
- **React 19** - 用于构建用户界面的 JavaScript 库
- **App Router** - Next.js 13+ 的文件系统路由机制

### 样式和 UI (Styling & UI)
- **Tailwind CSS v4** - 实用优先的 CSS 框架
- **shadcn/ui** - 基于 Radix UI 和 Tailwind CSS 的可访问组件库
- **Lucide React** - 简洁的 SVG 图标库

### 状态管理和数据获取 (State Management & Data Fetching)
- **TanStack Query (React Query) v5** - 服务端状态管理库，提供数据获取、缓存、同步等功能
- **React Hooks** - React 内置状态和副作用管理

### 类型安全 (Type Safety)
- **TypeScript** - JavaScript 的超集，提供静态类型检查

### 构建工具 (Build Tools)
- **Turbopack** - Next.js 的实验性打包工具，提供更快的构建速度
- **PostCSS** - CSS 处理工具
- **ESLint** - JavaScript/TypeScript 代码质量检查工具

### 开发工具 (Development Tools)
- **Prettier** - 代码格式化工具

## 功能特性 (Features)

- 🚀 基于 Next.js 15 和 React 19 构建
- ⚡ 使用实验性 Turbopack 提升构建速度
- 🎨 使用 Tailwind CSS v4 进行样式设计
- 🧠 TypeScript 提供类型安全
- 📱 响应式设计
- 🌙 深色模式支持
- 🔧 ESLint 保证代码质量
- 📝 笔记管理 (创建、读取、删除操作)
- 🌤️ 天气 API 集成
- 🧩 shadcn/ui 组件库
- 📚 全面的学习示例
- 🔄 TanStack Query 实现数据获取、缓存和状态管理
- 🏗️ 模块化架构设计

## 项目结构 (Project Structure)

```
.
├── app/                           # App Router 目录
│   ├── api/                       # API 路由
│   │   └── backend/               # 后端代理 API 端点
│   ├── shared-layout/             # 共享布局示例
│   ├── tailwind-learn/            # Tailwind CSS 学习页面
│   ├── shadcn-learn/              # shadcn/ui 学习页面
│   ├── tanstack-learn/            # TanStack Query 学习页面
│   ├── cms-learn/                 # CMS 服务学习页面
│   ├── semantic-html-learn/       # 语义化 HTML 学习页面
│   ├── use-xxx-tanstack-learn/    # 使用自定义 hooks 的 TanStack 学习页面
│   ├── globals.css                # 全局样式
│   ├── layout.tsx                 # 根布局
│   └── page.tsx                   # 首页
├── components/                    # 自定义组件
│   ├── ui/                        # shadcn/ui 组件
│   └── typography.tsx             # 语义化 HTML 组件
├── lib/                           # 工具函数
├── public/                        # 静态资源
├── shared/                        # 共享模块
│   ├── api/                       # API 服务层
│   │   ├── httpService/           # HTTP 请求服务
│   │   │   ├── httpService.api.ts # HTTP 服务接口定义
│   │   │   ├── httpService.ts     # HTTP 服务实现
│   │   │   └── index.ts           # 模块导出
│   │   ├── notes/                 # 笔记 API 模块
│   │   │   ├── domain.ts          # 领域模型和类型定义
│   │   │   ├── notesService.ts    # 笔记服务实现
│   │   │   ├── useNotes.ts        # React Query hooks
│   │   │   └── index.ts           # 模块导出
│   │   ├── users/                 # 用户 API 模块
│   │   │   ├── domain.ts          # 领域模型和类型定义
│   │   │   ├── usersService.ts    # 用户服务实现
│   │   │   ├── useUsers.ts        # React Query hooks
│   │   │   └── index.ts           # 模块导出
│   │   ├── posts/                 # 文章 API 模块
│   │   │   ├── domain.ts          # 领域模型和类型定义
│   │   │   ├── postsService.ts    # 文章服务实现
│   │   │   ├── usePosts.ts        # React Query hooks
│   │   │   └── index.ts           # 模块导出
│   │   ├── weather/               # 天气 API 模块
│   │   │   ├── domain.ts          # 领域模型和类型定义
│   │   │   ├── weatherService.ts  # 天气服务实现
│   │   │   ├── useWeather.ts      # React Query hooks
│   │   │   └── index.ts           # 模块导出
│   │   └── cms/                   # CMS API 模块
│   │       ├── domain.ts          # 领域模型和类型定义
│   │       ├── cmsService.ts      # CMS 服务实现
│   │       ├── useFeaturedDaos.ts # React Query hooks
│   │       └── index.ts           # 模块导出
│   └── types/                     # 共享类型定义
├── modules/                       # 应用模块
│   └── application/               # 应用级工具和配置
│       ├── constants/             # 应用常量
│       │   └── reactQuery.ts     # React Query 配置
│       └── utils/                # 应用工具类
│           ├── queryClientUtils/  # QueryClient 工具
│           ├── proxyBackendUtils/ # API 代理工具
│           ├── middlewareUtils/   # 中间件工具
│           ├── fetchInterceptorUtils/ # Fetch 拦截工具
│           └── eventBus/          # 事件总线工具
└── ...
```

## 模块架构 (Modules Architecture)

项目采用模块化架构设计，将功能按照业务领域划分为独立的模块，每个模块遵循统一的结构模式：

### 1. 模块结构模式 (Module Structure Pattern)
每个业务模块都遵循相同的文件结构：
```
module-name/
├── domain.ts          # 领域模型和类型定义
├── service.ts         # 服务实现（继承 HttpService）
├── useModule.ts       # React Query hooks
└── index.ts           # 模块导出
```

### 2. 核心模块详解 (Core Modules Details)

#### HttpService 模块
所有 API 服务的基础模块：
- **职责**: 提供统一的 HTTP 请求处理能力
- **功能**: 请求发送、响应处理、错误处理、参数序列化
- **设计模式**: 基础服务类，其他服务模块继承此类
- **文件结构**:
  - [httpService.api.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/httpService/httpService.api.ts): 定义接口和类型
  - [httpService.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/httpService/httpService.ts): 核心实现
  - [index.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/node_modules/@shadcn/ui/src/index.ts): 模块导出

#### Notes 模块 (笔记管理)
核心业务模块之一，实现笔记的增删查功能：
- **领域模型**: Note 接口、CreateNoteRequest、DeleteNoteRequest
- **服务层**: NotesService (继承 HttpService)
- **数据层**: useNotes、useCreateNote、useDeleteNote hooks
- **特点**: 完整的 CRUD 操作示例
- **文件结构**:
  - [domain.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/weather/domain.ts): 定义 Note 相关接口和类型
  - [notesService.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/notes/notesService.ts): 实现笔记服务
  - [useNotes.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/notes/useNotes.ts): React Query hooks
  - [index.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/node_modules/@shadcn/ui/src/index.ts): 模块导出

#### Users 模块 (用户管理)
用户相关功能模块：
- **领域模型**: User 接口、CreateUserRequest、GetUsersRequest
- **服务层**: UsersService (继承 HttpService)
- **数据层**: useUsers、useCreateUser、useUser hooks
- **特点**: 包含依赖查询示例
- **文件结构**:
  - [domain.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/weather/domain.ts): 定义 User 相关接口和类型
  - [usersService.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/users/usersService.ts): 实现用户服务
  - [useUsers.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/users/useUsers.ts): React Query hooks
  - [index.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/node_modules/@shadcn/ui/src/index.ts): 模块导出

#### Posts 模块 (文章管理)
文章内容管理模块：
- **领域模型**: Post 接口、GetPostsRequest
- **服务层**: PostsService (继承 HttpService)
- **数据层**: usePosts、useInfinitePosts hooks
- **特点**: 支持分页和无限滚动加载
- **文件结构**:
  - [domain.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/weather/domain.ts): 定义 Post 相关接口和类型
  - [postsService.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/posts/postsService.ts): 实现文章服务
  - [usePosts.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/posts/usePosts.ts): React Query hooks
  - [index.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/node_modules/@shadcn/ui/src/index.ts): 模块导出

#### Weather 模块 (天气服务)
第三方 API 集成示例：
- **领域模型**: WeatherData 接口、GetWeatherRequest
- **服务层**: WeatherService (继承 HttpService)
- **数据层**: useWeather hook
- **特点**: 展示外部 API 集成方式
- **文件结构**:
  - [domain.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/weather/domain.ts): 定义天气相关接口和类型
  - [weatherService.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/weather/weatherService.ts): 实现天气服务
  - [useWeather.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/weather/useWeather.ts): React Query hooks
  - [index.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/node_modules/@shadcn/ui/src/index.ts): 模块导出

#### CMS 模块 (内容管理)
内容管理系统模块：
- **领域模型**: IFeaturedDao、IWhitelistedAddresses 等接口
- **服务层**: CmsService (继承 HttpService)
- **数据层**: useFeaturedDaos hook
- **特点**: 展示复杂数据结构处理
- **文件结构**:
  - [domain.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/weather/domain.ts): 定义 CMS 相关接口和类型
  - [cmsService.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/cms/cmsService.ts): 实现 CMS 服务
  - [useFeaturedDaos.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/shared/api/cms/useFeaturedDaos.ts): React Query hooks
  - [index.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/node_modules/@shadcn/ui/src/index.ts): 模块导出

#### SharedDataContext 模块
用于在多个页面间共享数据的上下文模块：
- **职责**: 提供跨页面数据共享和持久化
- **功能**: 
  - 用户信息共享
  - 主题设置共享
  - 通知消息共享
  - localStorage 数据持久化
- **设计模式**: React Context API
- **文件结构**:
  - [SharedDataContext.tsx](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/modules/application/sharedDataContext/SharedDataContext.tsx): 上下文实现
  - [index.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/node_modules/@shadcn/ui/src/index.ts): 模块导出
  - [README.md](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/README.md): 使用文档

### 3. 模块间关系 (Module Relationships)
```
HttpService (基础服务)
    ↓ (继承)
NotesService → useNotes (数据 hooks)
UsersService → useUsers (数据 hooks)
PostsService → usePosts (数据 hooks)
WeatherService → useWeather (数据 hooks)
CmsService → useFeaturedDaos (数据 hooks)
```

### 4. 模块设计原则 (Module Design Principles)
- **单一职责**: 每个模块只负责一个业务领域
- **高内聚低耦合**: 模块内部高度相关，模块间依赖清晰
- **可复用性**: 遵循统一模式，便于扩展新模块
- **类型安全**: 使用 TypeScript 保证编译时类型检查
- **一致性**: 所有模块遵循相同的结构和命名规范

### 5. 应用工具类 (Application Utilities)

#### QueryClient 配置
用于配置 TanStack Query 客户端的全局设置：
- **位置**: [/modules/application/constants/reactQuery.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/modules/application/constants/reactQuery.ts)
- **功能**: 
  - 设置默认查询选项（如 staleTime、retry 等）
  - 提供统一的 QueryClient 配置
- **使用**: 通过 QueryClientUtils 在服务端和客户端创建 QueryClient 实例

#### EventBus 工具
用于组件间通信的事件总线工具：
- **位置**: [/modules/application/utils/eventBus/](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/modules/application/utils/eventBus/)
- **功能**: 
  - 事件订阅 (on)
  - 事件取消订阅 (off)
  - 事件触发 (trigger)
  - 支持泛型类型安全
- **使用**: 导入 [eventBus](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/modules/application/utils/eventBus/eventBus.ts#L72-L72) 实例使用事件通信

##### 使用示例:

```typescript
import { eventBus } from '@/modules/application/utils/eventBus';

// 定义事件常量
const USER_LOGIN = 'userLogin';
const DATA_REFRESH = 'dataRefresh';

// 订阅事件
const unsubscribe = eventBus.on(USER_LOGIN, (userData: { id: number; name: string }) => {
  console.log('User logged in:', userData);
});

// 触发事件
eventBus.trigger(USER_LOGIN, { id: 1, name: 'John Doe' });

// 取消订阅
unsubscribe();
// 或者
eventBus.off(USER_LOGIN, callbackFunction);
```

#### Data Caching Strategy
The application implements intelligent data caching using TanStack Query:
- **Default Cache Time**: 1 minute fresh data, 5 minutes cache retention
- **Notes Data**: 5 minutes fresh data, 10 minutes cache retention
- **Weather Data**: 30 minutes fresh data, 1 hour cache retention
- **Auto Refresh**: Automatic background refresh after data expiration
- **Error Retry**: Automatic retry mechanism on query failure

#### PageContainer Component
用于包装页面内容并支持服务端数据预取的容器组件：
- **位置**: [/components/PageContainer.tsx](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/components/PageContainer.tsx)
- **功能**: 
  - 作为页面的根容器组件
  - 接收预取的 QueryClient 实例以实现服务端数据预取
  - 通过 HydrationBoundary 组件在服务端和客户端之间同步 React Query 状态
  - 使用 dehydrate 函数将 QueryClient 状态序列化传递给 HydrationBoundary
  - 提供统一的页面布局和样式
- **使用**: 在页面组件中使用，支持服务端数据预取和客户端缓存同步

##### 使用步骤 (Usage Steps):

1. **在页面组件中导入 PageContainer**:
   ```tsx
   import { PageContainer } from "@/components/PageContainer";
   import { queryClientUtils } from '@/modules/application/utils/queryClientUtils';
   import { notesOptions } from '@/shared/api/notes/useNotes';
   ```

2. **创建 QueryClient 实例并预取数据**:
   ```tsx
   export default async function HomePage() {
       const queryClient = queryClientUtils.getQueryClient();
       
       // Prefetch data on the server
       await queryClient.prefetchQuery(notesOptions());
   }
   ```

3. **使用 PageContainer 包装页面内容**:
   ```tsx
   return (
       <PageContainer queryClient={queryClient}>
           <HomePageClient />
       </PageContainer>
   );
   ```

##### 工作原理 (How it works):

1. **服务端预取**: 在服务端渲染期间，PageContainer 接收预取的 QueryClient 实例
2. **状态序列化**: 使用 dehydrate 函数将 QueryClient 中的缓存数据序列化
3. **HydrationBoundary**: 通过 HydrationBoundary 将序列化的状态传递给客户端
4. **客户端 Hydration**: 客户端使用序列化的状态初始化 QueryClient，避免重复请求

##### 优势 (Benefits):

- **性能优化**: 减少客户端初始请求，提高页面加载速度
- **SEO 友好**: 服务端渲染完整内容，提升搜索引擎优化
- **用户体验**: 页面加载时显示缓存数据，减少加载等待时间
- **数据一致性**: 确保服务端和客户端数据状态一致

#### HydrationBoundary
用于在服务端渲染和客户端 hydration 之间同步 React Query 状态：
- **功能**:
  - 将服务端预取的数据状态传递给客户端
  - 确保客户端 hydration 时数据状态的一致性
  - 避免客户端重复请求已预取的数据
- **使用**: 通过 PageContainer 组件包装页面内容，自动处理 hydration 过程

##### 完整的 Hydration 模式实现

本项目实现了完整的 React Query Hydration 模式，包括：

1. **服务端预取**: 在 Next.js 服务端渲染期间预取数据
2. **状态序列化**: 使用 `dehydrate` 函数序列化 QueryClient 状态
3. **HydrationBoundary**: 通过 HydrationBoundary 组件传递序列化状态
4. **客户端恢复**: 客户端使用 `hydrate` 函数恢复 QueryClient 状态

这种模式确保了：
- 首次页面加载时显示预取的数据
- 客户端不需要重新请求已预取的数据
- 数据在服务端和客户端之间保持一致
- 更好的性能和用户体验

##### QueryClient 配置标准化

为了确保整个应用中 React Query 行为的一致性，我们使用共享的 QueryClient 配置：

```ts
// modules/application/constants/reactQuery.ts
import type { QueryClientConfig } from '@tanstack/react-query';

export const queryClientConfig: QueryClientConfig = {
    defaultOptions: {
        queries: {
            staleTime: 60_000, // 1 minute
            retry: 0,
        },
    },
};
```

使用标准化的配置确保了：
- 一致的缓存策略
- 统一的重试机制
- 可预测的数据获取行为
- 更容易的调试和维护

#### ProxyBackendUtils (API 代理工具)
用于处理 API 请求代理和模拟的工具类：
- **位置**: [/modules/application/utils/proxyBackendUtils/](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/modules/application/utils/proxyBackendUtils/)
- **功能**:
  - 代理 API 请求到外部后端服务（当配置了 APP_BACKEND_URL 时）
  - 在开发环境中直接处理 API 请求（无外部后端时）
  - 管理不同端点的请求处理（notes, users, posts, weather）
- **使用**: 通过 [/app/api/backend/[...url]/route.ts](file:///Users/mac/WebstormProjects/nextstudy/next-fullstack-notes/app/api/backend/%5B...url%5D/route.ts) 导出所有 HTTP 方法

## 应用文件说明 (Application Files)

### 1. 主页 (app/page.tsx)
应用的主页面，实现笔记的增删查功能：
- 使用 useNotes、useCreateNote、useDeleteNote hooks 管理笔记数据
- 集成天气 API，显示河南漯河的天气信息
- 实现响应式设计，支持深色模式

### 2. Tailwind CSS 学习页面 (app/tailwind-learn/page.tsx)
全面展示 Tailwind CSS 特性的学习页面：
- 布局系统演示 (Flexbox 和 Grid)
- 样式和效果展示
- 响应式设计示例
- 深色模式支持

### 3. 共享布局示例 (app/shared-layout/)
展示 Next.js 共享布局功能：
- page-one/page.tsx: 第一个示例页面
- page-two/page.tsx: 第二个示例页面
- layout.tsx: 共享布局组件

### 4. shadcn/ui 学习页面 (app/shadcn-learn/page.tsx)
展示 shadcn/ui 组件库的使用：
- 各种按钮样式
- 输入组件
- 卡片布局
- 警告框和徽章

### 5. TanStack Query 学习页面 (app/tanstack-learn/page.tsx)
全面展示 TanStack Query 功能：
- 数据获取 (useQuery)
- 数据修改 (useMutation)
- 无限滚动 (useInfiniteQuery)
- 依赖查询
- 错误处理和重试

### 6. CMS 学习页面 (app/cms-learn/page.tsx)
展示 CMS 服务的使用：
- 特色 DAO 数据展示
- 白名单地址管理
- 制裁地址检查

### 7. 语义化 HTML 学习页面 (app/semantic-html-learn/page.tsx)
展示语义化 HTML 的最佳实践：
- 正确使用 HTML5 语义化标签
- 可访问性优化
- SEO 友好结构

### 8. 自定义 Hooks 学习页面 (app/use-xxx-tanstack-learn/page.tsx)
展示如何使用自定义 React Query hooks：
- useUsers、useCreateUser、useUser
- usePosts、useInfinitePosts
- useWeather
- useNotes、useCreateNote、useDeleteNote

## 核心架构模式 (Core Architecture Patterns)

### 1. API 服务层架构 (API Service Layer Architecture)
采用分层架构模式，每个业务模块都有独立的服务层：
- **HttpService**: 基础 HTTP 请求服务类
- **领域服务类**: 继承 HttpService，如 NotesService、UsersService 等
- **React Query Hooks**: 基于 TanStack Query 的自定义 hooks，如 useNotes、useUsers 等

### 2. 数据获取模式 (Data Fetching Pattern)
使用 TanStack Query 管理服务端状态：
- `useQuery`: 数据获取和缓存
- `useMutation`: 数据修改操作
- `useInfiniteQuery`: 无限滚动分页

### 3. 组件设计模式 (Component Design Pattern)
- **语义化 HTML 组件**: 使用 React.forwardRef 创建可访问的语义化组件
- **shadcn/ui 组件**: 基于 Radix UI 构建的可访问组件

## 学习资源 (Learning Resources)

本项目包含多个学习页面，帮助理解不同技术：

### 1. 笔记应用 (`/`)
主页展示完整的 CRUD 应用：
- 创建笔记
- 读取笔记
- 删除笔记
- 实时获取河南漯河天气数据

### 2. Tailwind CSS 学习 (`/tailwind-learn`)
Tailwind CSS 特性全面指南：
- 布局系统 (Flexbox 和 Grid)
- 间距和尺寸
- 颜色和深色模式
- 排版
- 边框和效果
- 响应式设计
- 交互元素

### 3. 共享布局示例 (`/shared-layout/page-one`)
展示如何在多个页面间共享布局：
- 一致的导航
- 响应式设计
- 页面转换间的状态管理

### 4. shadcn/ui 学习 (`/shadcn-learn`)
shadcn/ui 组件库使用示例：
- 不同样式的按钮
- 输入框
- 复选框
- 警告框
- 卡片
- 徽章

### 5. TanStack Query 学习 (`/tanstack-learn`)
TanStack Query 库使用示例：
- 基础数据获取 (useQuery)
- 依赖查询
- 数据修改 (useMutation)
- 无限查询分页
- 缓存和后台数据同步
- 错误重试机制

### 6. CMS 服务学习 (`/cms-learn`)
CMS 服务集成示例：
- 特色 DAO 数据获取
- 白名单地址管理
- 制裁地址检查

### 7. 语义化 HTML 学习 (`/semantic-html-learn`)
语义化 HTML 最佳实践：
- 正确使用 HTML5 语义化标签
- 可访问性优化
- SEO 友好结构

## API 端点 (API Endpoints)

### 笔记 API
- `GET /api/backend/notes` - 获取所有笔记
- `POST /api/backend/notes` - 创建新笔记
- `POST /api/backend/notes` with `{ action: 'delete', id }` - 根据 ID 删除笔记

### 用户 API
- `GET /api/backend/users` - 获取所有用户
- `GET /api/backend/users?id={id}` - 获取特定用户
- `POST /api/backend/users` - 创建新用户

### 文章 API
- `GET /api/backend/posts` - 获取所有文章
- `GET /api/backend/posts?page={page}&limit={limit}` - 获取分页文章

### 天气 API
- `GET /api/backend/weather?city={city}` - 获取指定城市的天气数据

## 环境变量 (Environment Variables)

要使用天气 API，需要在 `.env.local` 文件中设置 WeatherAPI 密钥：

``env
WEATHER_API_KEY=your_api_key_here
```

在 [WeatherAPI.com](https://www.weatherapi.com/) 注册获取免费 API 密钥

## 开发启动 (Getting Started)

首先，安装依赖：

```bash
npm install
# or
yarn install
# or
pnpm install
# or
bun install
```

然后，运行开发服务器：

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

在浏览器中打开 [http://localhost:3000](http://localhost:3000) 查看结果。

您可以通过修改 `app/page.tsx` 来开始编辑页面。页面会在您编辑文件时自动更新。

## 部署 (Deployment)

部署 Next.js 应用最简单的方式是使用 [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme)（Next.js 创作者）。

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

## 进一步学习 (Learn More)

了解更多关于本项目使用的技术：

- [Next.js Documentation](https://nextjs.org/docs) - 学习 Next.js 特性和 API
- [Tailwind CSS Documentation](https://tailwindcss.com/docs) - 实用优先的 CSS 框架
- [shadcn/ui Documentation](https://ui.shadcn.com/) - 可访问和可定制的组件
- [Learn Next.js](https://nextjs.org/learn) - 交互式 Next.js 教程
- [TypeScript Documentation](https://www.typescriptlang.org/docs/) - 带类型的 JavaScript
- [TanStack Query Documentation](https://tanstack.com/query/latest) - 服务端状态管理

## 贡献 (Contributing)

欢迎贡献！请随时提交问题和拉取请求。

## 许可证 (License)

本项目基于 MIT 许可证。