Next.js 博客管理后台的技术选型与实践

// app/(dashboard)/layout.tsx — 服务端组件（纯结构，无交互）
export default function DashboardLayout({ children }: { children: React.ReactNode }) {
    return (
        <div className="flex h-screen">
            <Sidebar />          {/* 服务端渲染的侧边栏 */}
            <main className="flex-1 overflow-auto">
                {children}
            </main>
        </div>
    )
}

// components/features/ArticleTable.tsx — 客户端组件（有数据获取和搜索交互）
'use client'

export default function ArticleTable() {
    const [search, setSearch] = useState('')
    const { data, isLoading } = useArticles({ search })
    // ...
}

app/
├── (auth)/            # 认证页面组（独立布局，不显示侧边栏）
│   ├── login/page.tsx
│   └── layout.tsx
└── (dashboard)/       # 后台管理组（有侧边栏的布局）
    ├── articles/page.tsx
    ├── comments/page.tsx
    └── layout.tsx

// hooks/useDashboardStats.ts
import { useQuery } from '@tanstack/react-query'

export function useDashboardStats() {
    // 业务指标（Micrometer）
    const { data: metrics, isLoading: metricsLoading } = useQuery({
        queryKey: ['dashboard', 'metrics'],
        queryFn: getDashboardMetrics,
        staleTime: 1000 * 60,      // 1 分钟内不重新请求
        refetchInterval: 1000 * 30, // 每 30 秒自动轮询刷新
    })

    // 系统健康状态
    const { data: healthData, isLoading: healthLoading } = useQuery({
        queryKey: ['dashboard', 'health'],
        queryFn: getHealth,
        staleTime: 1000 * 30,
        refetchInterval: 1000 * 60,
    })

    return { metrics, healthData, isLoading: metricsLoading || healthLoading }
}

const queryClient = useQueryClient()

const deleteMutation = useMutation({
    mutationFn: (id: string) => deleteArticle(id),
    onSuccess: () => {
        // 标记文章列表缓存为过期，触发重新请求
        queryClient.invalidateQueries({ queryKey: ['articles'] })
        toast({ title: '删除成功' })
    },
    onError: (error) => {
        toast({ title: '删除失败', description: error.message, variant: 'destructive' })
    }
})

// stores/useAuthStore.ts
import { create } from 'zustand'
import { persist } from 'zustand/middleware'

interface AuthState {
    user: User | null
    token: string | null
    tokenExpiresAt: number | null
    isAuthenticated: boolean
    login: (user: User, token: string, expiresIn: number) => void
    logout: () => Promise<void>
    isTokenExpired: () => boolean
}

export const useAuthStore = create<AuthState>()(
    persist(
        (set, get) => ({
            user: null,
            token: null,
            tokenExpiresAt: null,
            isAuthenticated: false,

            login: (user, token, expiresIn) => {
                const expiresAt = Date.now() + expiresIn * 1000
                localStorage.setItem('token', token)
                Cookies.set('token', token, { expires: 1 })
                set({ user, token, tokenExpiresAt: expiresAt, isAuthenticated: true })
            },

            logout: async () => {
                try {
                    await apiLogout()  // 调用后端让 Token 失效
                } finally {
                    localStorage.removeItem('token')
                    Cookies.remove('token')
                    set({ user: null, token: null, isAuthenticated: false })
                }
            },

            isTokenExpired: () => {
                const { tokenExpiresAt } = get()
                if (!tokenExpiresAt) return true
                return Date.now() > tokenExpiresAt
            },
        }),
        {
            name: 'auth-storage',
            // 只持久化必要字段，避免存入 action 函数
            partialize: (state) => ({
                user: state.user,
                token: state.token,
                tokenExpiresAt: state.tokenExpiresAt,
                isAuthenticated: state.isAuthenticated,
            }),
        }
    )
)

// lib/validations.ts
import { z } from 'zod'

export const ArticleSchema = z.object({
    title: z.string()
        .min(1, '标题不能为空')
        .max(255, '标题最多255字符'),

    summary: z.string()
        .max(500, '摘要最多500字符')
        .optional()
        .or(z.literal('')),  // 允许空字符串（可选字段常见需求）

    content: z.string()
        .min(10, '内容至少10字符'),

    categoryId: z.string().min(1, '请选择分类'),

    tagIds: z.array(z.string())
        .max(5, '最多选择5个标签')
        .default([]),

    type: z.union([z.literal(1), z.literal(2), z.literal(3)]).default(1),

    isTop: z.union([z.literal(0), z.literal(1)]).default(0),
})

// 从 Schema 推导出 TypeScript 类型，无需重复定义
export type ArticleFormData = z.infer<typeof ArticleSchema>

// ❌ 旧做法：手动维护类型和验证规则两份代码
type ArticleFormData = { title: string; content: string; ... }
function validate(data: ArticleFormData) { /* 手写验证逻辑 */ }

// ✅ 新做法：Schema 是唯一数据源
export type ArticleFormData = z.infer<typeof ArticleSchema>
// 修改 Schema 时，类型自动同步，不会出现类型和验证不一致的 Bug

npx shadcn@latest add table
npx shadcn@latest add form
npx shadcn@latest add dialog

全局状态
├── 服务端状态（TanStack Query 管理）
│   ├── 文章列表、文章详情
│   ├── 评论列表
│   ├── 文件列表
│   └── 系统监控指标（定时轮询）
│
└── 客户端状态（Zustand 管理）
    ├── 用户认证状态（isAuthenticated、user、token）
    └── UI 偏好（侧边栏折叠）