一、标准 React + TS 项目目录结构

通用的目录骨架。后续逐个解析：

your-project/
├── public/ # 静态资源
├── src/
│ ├── api/ # 接口请求封装
│ ├── assets/ # 静态资源
│ ├── components/ # 通用组件
│ │ ├── common/ # 基础组件
│ │ └── business/ # 业务通用组件
│ ├── hooks/ # 自定义 Hooks
│ ├── layouts/ # 布局组件
│ ├── pages/ # 页面组件
│ │ ├── Home/ # 首页
│ │ ├── User/ # 使用者模块
│ │ │ ├── List/ # 使用者列表页
│ │ │ └── Detail/ # 使用者详情页
│ │ └── NotFound/ # 404页面
│ ├── router/ # 路由配置
│ ├── store/ # 状态管理
│ ├── types/ # 全局类型定义
│ ├── utils/ # 工具函数
│ ├── App.tsx # 根组件
│ ├── main.tsx # 入口文件
│ └── vite-env.d.ts # Vite TS 类型声明
├── .eslintrc.cjs # ESLint 配置
├── tsconfig.json # TypeScript 配置
├── vite.config.ts # Vite 配置
└── package.json # 依赖管理

二、各文件夹 / 文件解析

. public/ - 静态资源

痛点这方面，不知道什么时候该放在 public，结果导致资源无法被建立工具处理或方法失效。话说回来，

作用

存放无需经过 Vite 打包的静态资源。直接复制到打包后的 dist 根目录，访问方法为 /文件名。老实说，

常见文件

• favicon.ico网站图标
• robots.txt搜索引擎爬虫规则
• index.htmlHTML 入口模板

知识点关联

• React 是「SPA 单页应用」。仅需一个 HTML 入口；
• 静态资源的两种加载方式：public vs src/assets。

. src/assets/ - 静态资源

从痛点来看，图片方法写死导致缓存失效或建立报错。

作用

存放需要的静态资源，打包后会被哈希命名。

示例代码

// src/pages/Home/Home.tsx
import React from 'react';import logo from '@/assets/logo.png';// 别名 @ 指向 src
const Home = => {
return;// 打包后会替换为哈希后的方法
};export default Home;

知识点关联

• 模块导入资源：Vite/Webpack 支持将资源作为模块导入，TS 需在 vite-env.d.ts 中声明类型；
• 样式模块化：If storing CSS/SCSS。combine with C​SS Modules to avoid style leakage.

. src/types/ - 全局 TS 类型定义

痛点的观点是，接口返回类型不统一，导致 IDE 提示失效和运行时错误。

作用

存放项目全局的 TypeScript 接口、类型别名、枚举。统一管理类型，避免重复定义。不过，

示例代码

// src/types/user.ts
// 枚举
export enum UserRole {
Admin = 'admin'。User = 'user',Guest = 'guest'
}
// 接口
export interface UserInfo {
id的观点是，string;name: string;age，: number;// 可选属性
至于role，UserRole;createTime: Date;}
// 请求参数 / 响应体结构
export interface UserListRequest {
从page来看，number;size: number;keyword，: string;}
export interface UserListResponse {
list的观点是，UserInfo;total: number;}

知识点关联

• T​S 接口 / 类型别名：`Props`、API 数据、状态管理的类型约束主要；说起来，
• T​S 泛型：`useRequest` 等提高复用性；
• T​S 类型 ：`interface extends` 实现复用，如 `BaseResponse` 包裹所有接口响应。

. src/utils/ - 工具函数

从痛点来看。工具函数散落各处，难以统一维护和测试。

作用

存放通用工具函数，如时间格式化、防抖节流、本地存储、URL解析等。

示例代码——时间格式化

// src/utils/format.ts
/** 时间格式化 */
export const formatDate = (
从date来看。Date | string,format = 'YYYY-MM-DD'
): string => {
const targetDate = typeof date === 'string'?new Date : date;const year = targetDate.getFullYear;const month = String + 1).padStart;const day = String).padStart;return format.replace)
.replace
.replace;}，

示例代码——Axios 封装

// src/utils/request.ts
import axios from 'axios';import type { AxiosRequestConfig,AxiosResponse } from 'axios';话说回来，import type { BaseResponse } from '@/types/common';// 创建实例
const request = axios.create({
baseURL: import.meta.env.VITE_API_BASE_URL。timeout: 5000,});// 请求拦截器——统一添加 Token
request.interceptors.request.use => {
const token = localStorage.getItem;if config.headers.Authorization = `Bearer ${token}`;return config;})，// 响应拦截器——统一错误处理
request.interceptors.response.use(
=> {
if {
alert;return Promise.reject;}
return response.data.data;},=> {
alert;
return Promise.reject;}
)，// 泛型封装 API 方法
export const requestGet = :Promise{
return request.get;}，export const requestPost = :Promise{
return request.post;}，export default request;

知识点关联

• A​xios 拦截器：
• E​nvironment Variables：
• P​ure Functions：

. src/hooks/ - 自定义 Hooks

痛点这方面，业务逻辑散布在多个组件里导致重复代码和难以测试。

作用

抽取可复用的状态与副作用逻辑，是 React 函数组件复用的主要方案。老实说，

// src/hooks/useUser.ts
import { useState。useEffect } from 'react';import { requestGet } from '@/utils/request';import type { UserListResponse,UserInfo } from '@/types/user';// 获取使用者列表 —— 泛型 Hook 示例
export const useUserList = => {
const = useState;const = useState;const = useState;useEffect=>{
const fetchData= async =>{
setLoading;setError，try{
const data= await requestGet(
'/api/user/list'。{page,size}
);不过，setList，}catch{
setError.message);}finally{
setLoading;}
}，fetchData;},)，return {list,loading,error};}，// 通用防抖 Hook
export const useDebounce = :T=>{
const =useState;useEffect=>{
const timer=setTimeout=>setDebounced,delay);return=>clearTimeout;},)，return debounced;}，

• K​ey Rules of React Hooks：
• S​tate & Effect:
• C​ustom Hook Convention:
• T​S 泛型 Hook:` 可适配任意数据结构。

. src/components/ - 通用组件

• C​omponent 分类：

基础按钮示例

// src/components/common/Button/Button.tsx
import React from 'react';import './Button.scss';// Props 定义
interface ButtonProps{
type?这方面，'primary'|'secondary'|'danger';size，:'small'|'middle'|'large';onClick，话说回来，:=>void;disabled，:boolean;老实说，children:React.ReactNode;className，:string;其实，}
// 函数组件 + TS Props
const Button:React.FC=({
type='primary',size='middle',onClick。disabled=false,children,className=''
})=>{
const btnClass=`btn btn-${type} btn-${size} ${className}`;return (
{children});}，export default Button;老实说，

• T​ypeScript 为 Props 提供完整约束。使 IDE 能即时提示错误。

---

业务卡片示例

// src/components/business/UserCard/UserCard.tsx
import React from 'react';import type { UserInfo } from '@/types/user';import { formatDate } from '@/utils/format';import Button from '@/components/common/Button/Button';import './UserCard.scss';interface UserCardProps{
user :UserInfo;onEdit:=>void;// 父子通信回调
}
const UserCard :React.FC==>(


{user.name}

成员的观点是，{user.role}

创建时�>{formatDate}
onEdit} type='primary'>编辑

);export default UserCard;

• P​​rops 使用 TS 接口确保父子之间的数据契约安全。

---

hhh

。

---