React 19 官方开发规范完整版React 19 带来了编译器、Actions、Form 原生支持、Server Components、新 Hooks等重大特性开发规范相比 React 18 有颠覆性更新。这份规范是企业级、可直接落地的标准覆盖项目结构、代码风格、组件编写、 Hooks 、表单/ Actions、性能、TypeScript、最佳实践。一、核心原则React 19 必守优先使用 React 19 原生能力弃用旧方案表单用原生form actionuseActionState弃用 Formik / React Hook Form简单场景数据获取用use Suspense Server Components弃用冗余状态管理样式优先 CSS Modules / Tailwind禁止行内样式滥用组件必须纯函数化无副作用、无隐式依赖服务端组件RSC默认化能放服务端就不放客户端编译器优化优先减少手动 memoTypeScript 强制全量使用二、项目目录规范React 19 标准结构src/ ├── app/ # App Router 目录Next.js / React 19 标准 │ ├── page.tsx # 页面入口默认服务端组件 │ ├── layout.tsx # 根布局 │ ├── error.tsx # 错误边界 │ ├── loading.tsx # Suspense 加载 │ └── (routes)/ # 路由分组 ├── components/ # 公共组件 │ ├── ui/ # 基础 UIButton、Input │ ├── feature/ # 业务组件 │ └── client/ # 明确标记客户端组件 ├── lib/ # 工具函数、工具类 ├── actions/ # React 19 Server Actions ├── hooks/ // 自定义 Hooks ├── types/ # TS 类型定义 └── styles/ # 全局样式强制规则服务端组件不要写 ‘use client’客户端组件必须在文件顶部声明 ‘use client’所有页面默认服务端组件三、代码风格规范1. 命名规范组件大驼峰UserProfile.tsx文件与组件名一致UserProfile.tsx函数/变量小驼峰handleSubmit常量全大写下划线MAX_RETRY_COUNTServer Actions以action结尾submitFormAction自定义 Hooks以use开头useUserInfo2. 格式规范2 空格缩进语句末尾必须加分号JSX 单标签自闭合Input /导入顺序第三方库 → 公共组件 → 工具 → 样式禁止死代码未使用变量、import、函数必须清理四、组件编写规范React 19 核心1. 服务端组件默认无状态、无 Hooks、无事件监听直接获取数据、直接渲染可嵌套客户端组件但不能导入客户端组件的 Hooks// app/page.tsx 默认服务端组件 import { getUserList } from /actions/userActions export default async function HomePage() { const users await getUserList() // 直接 await 获取数据 return div{users.map(user p key{user.id}{user.name}/p)}/div }2. 客户端组件必须标记// components/client/LikeButton.tsx use client // 强制第一行 import { useState } from react export default function LikeButton() { const [like, setLike] useState(false) return button onClick{() setLike(!like)}{like ? 已赞 : 点赞}/button }3. 组件定义规则只使用箭头函数 / 函数声明禁止 class 组件Props 必须用 TS 定义必填/可选明确Props 解构使用提高可读性一个文件只导出一个默认组件逻辑与 UI 分离复杂组件拆分type UserCardProps { user: { id: string; name: string } onDelete?: (id: string) void } export default function UserCard({ user, onDelete }: UserCardProps) { return ( div classNamecard h3{user.name}/h3 {onDelete button onClick{() onDelete(user.id)}删除/button} /div ) }4. 组件主体内不写DOM操作因为每次数据状态改变刷新页面都会执行组件函数。五、React 19 Hooks 规范1. Hooks 使用顺序固定不嵌套、不条件执行2. 优先使用 React 19 新 HooksuseActionState表单状态useFormStatus表单提交状态useOptimistic乐观更新use读取 Promise / 上下文3. 禁用过时写法弃用useStateuseEffect获取数据弃用手动管理 loading/error4. 自定义 Hooks 规范必须以use开头内部只使用 Hooks返回值清晰使用数组或对象// hooks/useUserInfo.ts use client import { use } from react import { fetchUser } from /actions/userActions export function useUserInfo(userId: string) { const user use(fetchUser(userId)) // React 19 use() return { user } }六、React 19 表单与 Actions 规范最重要React 19原生支持表单彻底告别第三方库。1. Server Actions 定义// actions/userActions.ts use server // 服务端 Action export async function updateUserAction(prevState: any, formData: FormData) { const name formData.get(name) // 数据库操作 return { success: true, message: 保存成功 } }2. 表单组件客户端use client import { useActionState } from react import { updateUserAction } from /actions/userActions export default function UserForm() { // React 19 表单状态 const [state, formAction] useActionState(updateUserAction, null) const { pending } useFormStatus() // 提交状态 return ( form action{formAction} input namename defaultValue张三 / button disabled{pending} typesubmit {pending ? 保存中... : 保存} /button {state?.message p{state.message}/p} /form ) }3. 乐观更新useOptimisticconst [optimisticUsers, addOptimisticUser] useOptimistic( users, (state, newUser) [...state, newUser] )七、数据获取规范React 19服务端组件直接 await 获取数据客户端组件使用 use() Suspense禁止useEffect获取数据加载、错误使用loading.tsx/error.tsx// 客户端数据获取 use client import { use, Suspense } from react function UserData({ userId }: { userId: string }) { const user use(fetchUser(userId)) return div{user.name}/div } export default function UserPage() { return ( Suspense fallback{div加载中.../div} UserData userId1 / /Suspense ) }八、性能优化规范React 19 编译器优先 React 编译器自动优化无需手动 memo禁止滥用memo/useMemo/useCallback列表必须加key且不使用 index客户端组件尽量轻量化大组件拆分为服务端客户端// 正确 key users.map(user User key{user.id} user{user} /) // 错误 key禁止 users.map((user, idx) User key{idx} user{user} /)九、TypeScript 强制规范所有组件、函数、变量必须定义类型禁止使用any必须用unknown 类型守卫Props、Actions 返回值必须定义接口Server Actions 严格校验formDatatype User { id: string name: string age?: number // 可选 } type ActionState { success: boolean message?: string } export async function updateUserAction( prevState: ActionState, formData: FormData ): PromiseActionState { return { success: true } }十、禁止行为红线规范禁止在服务端组件使用use client、Hooks、事件禁止在客户端组件写耗时逻辑禁止useEffect充当数据请求禁止嵌套多层条件渲染导致难以维护禁止表单不使用action而用旧onSubmit禁止直接操作 DOM一律用 React 方式十一、Git / 提交规范feat: 新功能fix: 修复refactor: 重构style: 格式chore: 构建/工具docs: 文档示例feat: add user list server component总结React 19 最核心 5 条默认服务端组件客户端必须标记 ‘use client’表单用 action useActionState弃用第三方库数据获取用 await / use()禁止 useEffect靠 React 编译器优化少用 memo全量 TypeScript禁止 any
React 19 开发规范
React 19 官方开发规范完整版React 19 带来了编译器、Actions、Form 原生支持、Server Components、新 Hooks等重大特性开发规范相比 React 18 有颠覆性更新。这份规范是企业级、可直接落地的标准覆盖项目结构、代码风格、组件编写、 Hooks 、表单/ Actions、性能、TypeScript、最佳实践。一、核心原则React 19 必守优先使用 React 19 原生能力弃用旧方案表单用原生form actionuseActionState弃用 Formik / React Hook Form简单场景数据获取用use Suspense Server Components弃用冗余状态管理样式优先 CSS Modules / Tailwind禁止行内样式滥用组件必须纯函数化无副作用、无隐式依赖服务端组件RSC默认化能放服务端就不放客户端编译器优化优先减少手动 memoTypeScript 强制全量使用二、项目目录规范React 19 标准结构src/ ├── app/ # App Router 目录Next.js / React 19 标准 │ ├── page.tsx # 页面入口默认服务端组件 │ ├── layout.tsx # 根布局 │ ├── error.tsx # 错误边界 │ ├── loading.tsx # Suspense 加载 │ └── (routes)/ # 路由分组 ├── components/ # 公共组件 │ ├── ui/ # 基础 UIButton、Input │ ├── feature/ # 业务组件 │ └── client/ # 明确标记客户端组件 ├── lib/ # 工具函数、工具类 ├── actions/ # React 19 Server Actions ├── hooks/ // 自定义 Hooks ├── types/ # TS 类型定义 └── styles/ # 全局样式强制规则服务端组件不要写 ‘use client’客户端组件必须在文件顶部声明 ‘use client’所有页面默认服务端组件三、代码风格规范1. 命名规范组件大驼峰UserProfile.tsx文件与组件名一致UserProfile.tsx函数/变量小驼峰handleSubmit常量全大写下划线MAX_RETRY_COUNTServer Actions以action结尾submitFormAction自定义 Hooks以use开头useUserInfo2. 格式规范2 空格缩进语句末尾必须加分号JSX 单标签自闭合Input /导入顺序第三方库 → 公共组件 → 工具 → 样式禁止死代码未使用变量、import、函数必须清理四、组件编写规范React 19 核心1. 服务端组件默认无状态、无 Hooks、无事件监听直接获取数据、直接渲染可嵌套客户端组件但不能导入客户端组件的 Hooks// app/page.tsx 默认服务端组件 import { getUserList } from /actions/userActions export default async function HomePage() { const users await getUserList() // 直接 await 获取数据 return div{users.map(user p key{user.id}{user.name}/p)}/div }2. 客户端组件必须标记// components/client/LikeButton.tsx use client // 强制第一行 import { useState } from react export default function LikeButton() { const [like, setLike] useState(false) return button onClick{() setLike(!like)}{like ? 已赞 : 点赞}/button }3. 组件定义规则只使用箭头函数 / 函数声明禁止 class 组件Props 必须用 TS 定义必填/可选明确Props 解构使用提高可读性一个文件只导出一个默认组件逻辑与 UI 分离复杂组件拆分type UserCardProps { user: { id: string; name: string } onDelete?: (id: string) void } export default function UserCard({ user, onDelete }: UserCardProps) { return ( div classNamecard h3{user.name}/h3 {onDelete button onClick{() onDelete(user.id)}删除/button} /div ) }4. 组件主体内不写DOM操作因为每次数据状态改变刷新页面都会执行组件函数。五、React 19 Hooks 规范1. Hooks 使用顺序固定不嵌套、不条件执行2. 优先使用 React 19 新 HooksuseActionState表单状态useFormStatus表单提交状态useOptimistic乐观更新use读取 Promise / 上下文3. 禁用过时写法弃用useStateuseEffect获取数据弃用手动管理 loading/error4. 自定义 Hooks 规范必须以use开头内部只使用 Hooks返回值清晰使用数组或对象// hooks/useUserInfo.ts use client import { use } from react import { fetchUser } from /actions/userActions export function useUserInfo(userId: string) { const user use(fetchUser(userId)) // React 19 use() return { user } }六、React 19 表单与 Actions 规范最重要React 19原生支持表单彻底告别第三方库。1. Server Actions 定义// actions/userActions.ts use server // 服务端 Action export async function updateUserAction(prevState: any, formData: FormData) { const name formData.get(name) // 数据库操作 return { success: true, message: 保存成功 } }2. 表单组件客户端use client import { useActionState } from react import { updateUserAction } from /actions/userActions export default function UserForm() { // React 19 表单状态 const [state, formAction] useActionState(updateUserAction, null) const { pending } useFormStatus() // 提交状态 return ( form action{formAction} input namename defaultValue张三 / button disabled{pending} typesubmit {pending ? 保存中... : 保存} /button {state?.message p{state.message}/p} /form ) }3. 乐观更新useOptimisticconst [optimisticUsers, addOptimisticUser] useOptimistic( users, (state, newUser) [...state, newUser] )七、数据获取规范React 19服务端组件直接 await 获取数据客户端组件使用 use() Suspense禁止useEffect获取数据加载、错误使用loading.tsx/error.tsx// 客户端数据获取 use client import { use, Suspense } from react function UserData({ userId }: { userId: string }) { const user use(fetchUser(userId)) return div{user.name}/div } export default function UserPage() { return ( Suspense fallback{div加载中.../div} UserData userId1 / /Suspense ) }八、性能优化规范React 19 编译器优先 React 编译器自动优化无需手动 memo禁止滥用memo/useMemo/useCallback列表必须加key且不使用 index客户端组件尽量轻量化大组件拆分为服务端客户端// 正确 key users.map(user User key{user.id} user{user} /) // 错误 key禁止 users.map((user, idx) User key{idx} user{user} /)九、TypeScript 强制规范所有组件、函数、变量必须定义类型禁止使用any必须用unknown 类型守卫Props、Actions 返回值必须定义接口Server Actions 严格校验formDatatype User { id: string name: string age?: number // 可选 } type ActionState { success: boolean message?: string } export async function updateUserAction( prevState: ActionState, formData: FormData ): PromiseActionState { return { success: true } }十、禁止行为红线规范禁止在服务端组件使用use client、Hooks、事件禁止在客户端组件写耗时逻辑禁止useEffect充当数据请求禁止嵌套多层条件渲染导致难以维护禁止表单不使用action而用旧onSubmit禁止直接操作 DOM一律用 React 方式十一、Git / 提交规范feat: 新功能fix: 修复refactor: 重构style: 格式chore: 构建/工具docs: 文档示例feat: add user list server component总结React 19 最核心 5 条默认服务端组件客户端必须标记 ‘use client’表单用 action useActionState弃用第三方库数据获取用 await / use()禁止 useEffect靠 React 编译器优化少用 memo全量 TypeScript禁止 any
