生产级 TypeScript/JavaScript 代码的核心在于建立清晰、可维护、可扩展的工程模式。本文基于 Everything Claude Code 的 Skill 体系，系统化拆解前端组件设计、后端架构分层与 RESTful API 设计的具体规范。通过遵循这些模式并借助 AI 编程助手（如 Claude Code）自动化检测与生成，团队能显著提升代码质量、开发效率与系统可维护性，避免常见陷阱。

TypeScript/JavaScript 生产级模式：前端组件、后端分层与 API 设计规范

在 AI 辅助编程成为主流的今天，生成代码的效率已非瓶颈，确保代码具备生产级质量才是关键挑战。模糊的命名、混乱的状态、耦合的逻辑和不一致的 API 会迅速积累技术债。本文将整合 Everything Claude Code 中的 coding-standards、frontend-patterns、backend-patterns 和 api-design 四个核心 Skill，为你拆解一套可被 AI 编程助手理解并执行的生产级模式规范。

这些 Skill 并非孤立的规则列表，而是一个可协同的体系。它们能在代码生成、审查、重构的各个环节被 AI 助手触发，从命名、结构到业务逻辑进行全方位的规范守护。

一、编码规范基础：命名、不可变性与类型安全

生产代码的基石是清晰的约定。coding-standards Skill 定义了跨语言、跨框架的通用规范，确保 AI 生成的代码从第一行开始就具备可读性。

1.1 命名规范：语义化是第一要务

变量、函数、组件和文件的命名必须准确描述其用途，避免歧义。

// GOOD
const isUserAuthenticated = true
const calculateSimilarity(a: number[], b: number[]) { }

// BAD
const flag = true
function similarity(a, b) { }

验证方法：让 AI Reviewer Agent 检查代码，若存在大量单字母变量或无意义前缀（如 temp, data），则需应用此规范。

1.2 不可变性：优先创建新对象

直接修改对象或数组属性是 bug 的温床。应使用展开运算符（...）或相关库创建新副本。

// GOOD: 创建新对象
const updatedUser = { ...user, name: 'New Name' }
const newList = [...oldList, newItem]

// BAD: 直接修改原对象
user.name = 'New Name'
oldList.push(newItem)

错误表现：直接修改可能引发难以追踪的渲染问题（React 状态不更新）或并发逻辑错误。

1.3 类型安全：善用 TypeScript

杜绝 any，为组件 props、函数参数和返回值明确定义接口（interface）或类型（type）。

// GOOD
interface ButtonProps {
  variant: 'primary' | 'secondary'
  children: React.ReactNode
  onClick?: () => void
}
export function Button(props: ButtonProps) { ... }

// BAD
export function Button(props: any) { ... }

与 ESLint 的 @typescript-eslint/no-explicit-any 规则配合，可在 PreToolUse Hook 中强制拦截。

二、前端模式：组件组合与状态管理

frontend-patterns Skill 将 React/Next.js 的最佳实践模板化，指导 AI 生成结构清晰、易维护的 UI 代码。

2.1 组合模式优于继承

通过组合小型、专注的组件来构建复杂 UI，而非创建庞大的继承链。Card 组件是经典示例：

export function Card({ children, variant = 'default' }) {
  return <div className={`card card-${variant}`}>{children}</div>
}
export function CardHeader({ children }) { return <div className="card-header">{children}</div> }
export function CardBody({ children }) { return <div className="card-body">{children}</div> }

// 使用时自由组合
<Card>
  <CardHeader>标题</CardHeader>
  <CardBody>内容</CardBody>
</Card>

2.2 复合组件模式管理复杂状态

对于像 Tabs、Select 这样内部需要协调多个子组件的组件，复合组件模式通过 Context 共享状态，封装内部逻辑。

const TabsContext = createContext()

export function Tabs({ children, defaultTab }) {
  const [activeTab, setActiveTab] = useState(defaultTab)
  return (
    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
      {children}
    </TabsContext.Provider>
  )
}

export function Tab({ id, children }) {
  const context = useContext(TabsContext)
  return (
    <button className={context.activeTab === id ? 'active' : ''}
            onClick={() => context.setActiveTab(id)}>
      {children}
    </button>
  )
}

2.3 状态管理：按复杂度选择方案

局部状态：useState / useReducer。
跨组件共享：Context + useReducer 适用于中小型应用。
复杂全局状态：推荐 Zustand 等轻量级状态管理库，避免 Redux 的过度工程化。
服务端状态：使用 React Query/SWR 管理异步数据，自动处理缓存、重试和乐观更新。

// Zustand 示例
import { create } from 'zustand'

const useMarketStore = create((set) => ({
  markets: [],
  setMarkets: (markets) => set({ markets }),
}))

三、后端模式：分层架构与数据库优化

backend-patterns Skill 确保 Node.js/Express/Next.js API Routes 的代码具备高可测试性和可扩展性。

3.1 强制分层：Controller - Service - Repository

将职责严格分离，是构建可维护后端的核心。

Controller/Handler：处理 HTTP 请求/响应，调用 Service。
Service：封装核心业务逻辑，调用 Repository。
Repository：封装数据访问细节（如数据库查询），是唯一与数据源交互的层。

// repositories/marketRepository.ts
export interface MarketRepository {
  findById(id: string): Promise<Market | null>
  findActive(): Promise<Market[]>
}

// services/marketService.ts
export class MarketService {
  constructor(private marketRepo: MarketRepository) {}
  async getActiveMarkets() { return this.marketRepo.findActive() }
}

// app/api/markets/route.ts (Controller)
export async function GET() {
  const markets = await marketService.getActiveMarkets()
  return NextResponse.json({ data: markets })
}

验证方法：检查 route.ts 文件中是否直接出现了 SQL/ORM 查询语句。如果有，说明分层被破坏。

3.2 防御 N+1 查询

这是关系型数据库中最常见的性能陷阱。Skill 会引导 AI 生成批量查询代码。

// BAD: N+1 查询
const markets = await getMarkets()
for (const market of markets) {
  market.creator = await getUser(market.creator_id) // 循环 N 次
}

// GOOD: 批量查询与映射
const creatorIds = [...new Set(markets.map(m => m.creator_id))]
const creators = await getUsers(creatorIds) // 一次查询
const creatorMap = new Map(creators.map(c => [c.id, c]))
markets.forEach(market => {
  market.creator = creatorMap.get(market.creator_id)
})

错误表现：API 响应时间随数据量线性增长，在数据库监控中能看到大量相似查询。

3.3 横切关注点：缓存、鉴权与错误处理

这些逻辑应通过中间件或装饰器模式封装，避免散落在业务代码中。

缓存：Repository 层可包装为缓存层（Cache-Aside 模式）。
鉴权：使用中间件统一校验 JWT，或通过高阶函数封装权限检查。
错误处理：集中定义错误类型（如 NotFoundError, ValidationError），在 Controller 层统一捕获并转换为标准 HTTP 错误响应。

四、API 设计规范：契约先行

api-design Skill 将 RESTful 最佳实践固化为可检测的合约，确保接口一致性。

4.1 RESTful 资源命名

URL 应指向资源，使用复数名词和 kebab-case。

GET  /api/v1/users           // 获取用户列表
POST /api/v1/users           // 创建用户
GET  /api/v1/users/123       // 获取特定用户
GET  /api/v1/users/123/orders // 获取用户的订单（子资源）

// 避免
GET /api/v1/getUsers
GET /api/v1/user

4.2 统一的响应结构与状态码

所有响应都应包含在统一的信封（envelope）中，并正确使用 HTTP 状态码。

// 成功
{
  "data": { "id": "abc-123", "name": "Alice" }
}
// 错误
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Must be a valid email address" }
    ]
  }
}

状态码约定：201 Created（创建成功），204 No Content（删除成功），400 Bad Request（参数错误），404 Not Found（资源不存在）。

4.3 分页、过滤与排序

为列表端点提供标准化的查询参数。

# Offset 分页
GET /api/v1/users?page=2&per_page=20

# Cursor 分页（适合大数据集）
GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20

# 过滤与排序
GET /api/v1/orders?status=active&sort=-created_at

响应中应包含分页元数据（meta），如 total、page、total_pages 等。

五、质量保障：从规范到自动化

上述模式并非文档，而是可执行的技能。在 Everything Claude Code 体系中，它们通过以下方式落地：

自动生成：当你要求 AI “创建一个用户管理 API”时，backend-patterns 和 api-design Skill 会协同工作，直接生成分层清晰、符合 RESTful 规范的代码。
实时审查：Code Reviewer Agent 结合这些 Skill，在 PR 检查时自动检测反模式（如 any 类型、N+1 查询、不规范的 URL）。
重构引导：对遗留代码进行重构时，AI 会基于这些 Skill 提出分步修改建议，并生成符合新规范的代码 diff。

你可以结合 TypeScript 工具链与后端架构深入了解相关工具的集成。

FAQ

Q: 这些模式是否仅适用于 TypeScript？ A: coding-standards 和 api-design 的核心原则（如清晰命名、RESTful 设计）同样适用于 JavaScript。TypeScript 的类型系统是实现“类型安全”规范的最佳工具。

Q: 如何让已有的旧代码逐步采用这些模式？ A: 利用 coding-standards Skill 进行逐步重构。优先修复命名和不可变性问题，然后通过 backend-patterns Skill 引入 Service 层，逐步分离 Controller 中的业务逻辑。

Q: AI 生成的代码能直接用于生产吗？ A: 绝大多数情况下，遵循这些 Skill 生成的代码已达到生产级结构标准。但仍需结合具体业务逻辑进行测试，并通过 Verification Loop Skill 进行端到端验证。

Q: 这些规范会限制开发灵活性吗？ A: 规范旨在消除无意义的差异和常见错误，而非限制合理设计。在边界清晰的前提下（如分层、API 合约内），业务逻辑的实现仍保有充分灵活性。

TypeScript/JavaScript 生产级模式：前端组件、后端分层与 API 设计规范 #

一、编码规范基础：命名、不可变性与类型安全 #

1.1 命名规范：语义化是第一要务 #

1.2 不可变性：优先创建新对象 #

1.3 类型安全：善用 TypeScript #

二、前端模式：组件组合与状态管理 #

2.1 组合模式优于继承 #

2.2 复合组件模式管理复杂状态 #

2.3 状态管理：按复杂度选择方案 #

三、后端模式：分层架构与数据库优化 #

3.1 强制分层：Controller - Service - Repository #

3.2 防御 N+1 查询 #

3.3 横切关注点：缓存、鉴权与错误处理 #

四、API 设计规范：契约先行 #

4.1 RESTful 资源命名 #

4.2 统一的响应结构与状态码 #

4.3 分页、过滤与排序 #

五、质量保障：从规范到自动化 #

FAQ #