张翔
12 KiB
12 KiB
系统架构文档
架构概述
Novalon Website 采用现代化的前端架构设计，基于 Next.js 16 的 App Router 模式，实现了一个高性能、可维护的企业官网系统。
技术架构
整体架构图
┌─────────────────────────────────────────────────────────────┐
│ 客户端 (Browser) │
├─────────────────────────────────────────────────────────────┤
│ React 19 + TypeScript + Tailwind CSS + Framer Motion │
├─────────────────────────────────────────────────────────────┤
│ Next.js 16 App Router │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Pages │ │ Layouts │ │ Loading │ │
│ │ (路由页面) │ │ (布局组件) │ │ (加载状态) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ 组件层 (Components) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ UI 组件 │ │ 布局组件 │ │ 业务组件 │ │
│ │ (shadcn) │ │ (Layout) │ │ (Sections) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ 服务层 (Services) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ API Routes │ │ Server │ │ Utilities │ │
│ │ (Next.js) │ │ Actions │ │ (lib) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ 外部服务 (External) │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Resend │ │ CDN │ │
│ │ (邮件服务) │ │ (静态资源) │ │
│ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
技术选型理由
| 技术 | 选型理由 |
|---|---|
| Next.js 16 | 支持 App Router、静态导出、SEO 优化、服务端渲染 |
| React 19 | 最新特性、并发渲染、服务端组件支持 |
| TypeScript | 类型安全、开发体验提升、代码可维护性 |
| Tailwind CSS 4 | 原子化 CSS、快速开发、CSS-in-JS 零运行时 |
| Framer Motion | 声明式动画、手势支持、性能优秀 |
| shadcn/ui | 可定制、无依赖锁定、Radix UI 基础 |
目录结构设计
App Router 路由组织
src/app/
├── layout.tsx # 根布局 - 全局 Provider、字体、元数据
├── error.tsx # 全局错误边界
├── not-found.tsx # 404 页面
├── globals.css # 全局样式
│
├── (marketing)/ # 营销页面路由组
│ ├── layout.tsx # 营销布局 - Header + Footer
│ ├── page.tsx # 首页
│ ├── about/ # 关于我们
│ ├── services/ # 核心业务
│ │ ├── page.tsx # 列表页
│ │ └── [id]/ # 详情页 (动态路由)
│ ├── products/ # 产品服务
│ ├── cases/ # 成功案例
│ ├── news/ # 新闻动态
│ │ ├── page.tsx # 列表页
│ │ └── [slug]/ # 详情页
│ └── contact/ # 联系我们
│ ├── page.tsx # 页面
│ └── actions.ts # Server Actions
│
├── api/ # API 路由
│ └── contact/route.ts # 联系表单 API
│
├── privacy/ # 隐私政策
├── terms/ # 服务条款
└── preview/ # 预览页面
组件目录组织
src/components/
├── ui/ # 基础 UI 组件 (shadcn/ui)
│ ├── button.tsx # 按钮
│ ├── card.tsx # 卡片
│ ├── dialog.tsx # 对话框
│ ├── input.tsx # 输入框
│ ├── textarea.tsx # 文本域
│ ├── dropdown-menu.tsx # 下拉菜单
│ ├── toast.tsx # 提示
│ └── ...
│
├── layout/ # 布局组件
│ ├── header.tsx # 页头导航
│ ├── footer.tsx # 页脚
│ ├── mobile-menu.tsx # 移动端菜单
│ ├── mobile-tab-bar.tsx # 移动端底部导航
│ └── breadcrumb.tsx # 面包屑
│
├── sections/ # 页面区块组件
│ ├── hero-section.tsx # Hero 区域
│ ├── services-section.tsx # 服务区块
│ ├── products-section.tsx # 产品区块
│ ├── cases-section.tsx # 案例区块
│ ├── about-section.tsx # 关于区块
│ ├── news-section.tsx # 新闻区块
│ └── contact-section.tsx # 联系区块
│
├── effects/ # 视觉效果组件
│ ├── gradient-flow.tsx # 渐变流动
│ ├── data-particle-flow.tsx # 数据粒子
│ ├── geometric-shapes.tsx # 几何图形
│ ├── glow-effect.tsx # 发光效果
│ └── ...
│
├── seo/ # SEO 组件
│ └── structured-data.tsx # 结构化数据
│
└── analytics/ # 分析组件
└── web-vitals.tsx # Web Vitals 监控
核心模块设计
1. 路由系统
路由组 (Route Groups)
使用 (marketing) 路由组将营销相关页面组织在一起，共享相同的布局：
// src/app/(marketing)/layout.tsx
export default function MarketingLayout({ children }) {
return (
<div className="min-h-screen flex flex-col">
<Header />
<ErrorBoundary>
<main className="flex-1">{children}</main>
</ErrorBoundary>
<Footer />
</div>
);
}
动态路由
支持动态路由参数，如服务详情、产品详情、案例详情、新闻详情：
// src/app/(marketing)/services/[id]/page.tsx
export default function ServiceDetailPage({ params }) {
return <ServiceDetailClient id={params.id} />;
}
2. 状态管理
Context 使用
ThemeProvider- 主题状态管理WebVitals- 性能指标监控
本地状态
组件内部使用 React Hooks 管理本地状态：
useState- 组件状态useEffect- 副作用处理useCallback- 回调优化useRef- DOM 引用
3. 数据流
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 用户交互 │ ──▶ │ 表单验证 │ ──▶ │ API 请求 │
└─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ UI 更新 │ ◀── │ 状态更新 │ ◀── │ 响应处理 │
└─────────────┘ └─────────────┘ └─────────────┘
4. 样式系统
Tailwind CSS 配置
- CSS Variables 驱动主题
- 响应式断点：sm, md, lg, xl, 2xl
- 自定义颜色变量
类名管理
使用 cn() 工具函数合并类名：
import { cn } from '@/lib/utils';
<Button className={cn('base-classes', conditional && 'active-class')} />
5. 动画系统
Framer Motion 集成
- 页面过渡动画
- 滚动触发动画
- 手势交互
- 列表动画
性能优化
- 使用
dynamic动态导入大型动画组件 AnimatePresence处理组件卸载动画will-changeCSS 属性优化
性能优化策略
1. 代码分割
// 动态导入非首屏组件
const ServicesSection = dynamic(
() => import('@/components/sections/services-section'),
{ loading: () => <SectionSkeleton />, ssr: false }
);
2. 图片优化
- 使用 Next.js Image 组件
- 支持 WebP/AVIF 格式
- 响应式图片尺寸
- 懒加载
3. 字体优化
// Google Fonts 优化配置
const notoSansSC = Noto_Sans_SC({
weight: ['400', '500', '700'],
variable: '--font-noto-sans-sc',
subsets: ['latin'],
display: 'swap',
preload: true,
});
4. 静态导出
// next.config.ts
const nextConfig = {
output: 'export',
distDir: 'dist',
images: { unoptimized: true },
};
安全设计
1. XSS 防护
- 使用 DOMPurify 清理用户输入
- React 自动转义
- Content Security Policy
2. CSRF 防护
- 表单包含 CSRF Token
- 验证请求来源
3. 邮件表单安全
- 蜜罐字段检测机器人
- 提交时间验证
- 数学验证码
SEO 优化
1. 元数据配置
export const metadata: Metadata = {
title: { default: '...', template: '%s | ...' },
description: '...',
keywords: ['...'],
openGraph: { ... },
twitter: { ... },
};
2. 结构化数据
// Organization Schema
<OrganizationSchema />
// Website Schema
<WebsiteSchema />
3. 语义化 HTML
- 正确的标题层级 (h1-h6)
- 语义化标签 (header, main, footer, nav, article)
- ARIA 属性
可访问性设计
WCAG 2.1 AA 合规
- 颜色对比度 ≥ 4.5:1
- 键盘导航支持
- 屏幕阅读器兼容
- 焦点管理
- 跳过链接
焦点陷阱
// 移动端菜单焦点陷阱
const focusTrapRef = useFocusTrap<HTMLDivElement>(isOpen);
扩展性设计
1. 组件可复用
- UI 组件与业务逻辑分离
- Props 接口设计
- 组合模式
2. 配置驱动
// src/lib/constants.ts
export const NAVIGATION: NavigationItem[] = [
{ id: 'home', label: '首页', href: '/' },
// ...
];
3. 类型安全
// 类型定义
export interface NewsItem {
id: string;
title: string;
excerpt: string;
date: string;
category: NewsCategory;
image: string;
content: string;
}