backend-patterns

# 后端开发模式 可扩展服务器端应用的架构模式和最佳实践。 ## 何时激活此技能 - 设计 REST 或 GraphQL API 端点 - 实现 Repository、Service 或 Controller 层 - 优化数据库查询（N+1问题、索引、连接池） - 添加缓存（Redis、内存、HTTP缓存头） - 设置后台任务或异步处理 - 构建 API 的错误处理和验证 - 构建中间件（认证、日志、限流） ## API 设计模式 ### RESTful API 结构 ```typescript // 基于资源的 URL 设计 GET /api/markets # 列出资源 GET /api/markets/:id # 获取单个资源 POST /api/markets # 创建资源 PUT /api/markets/:id # 替换资源 PATCH /api/markets/:id # 更新资源 DELETE /api/markets/:id # 删除资源 // 查询参数用于过滤、排序、分页 GET /api/markets?status=active&sort=volume&limit=20&offset=0 ``` ### Repository 模式 将数据访问逻辑抽象为接口，便于切换数据源和单元测试。 ```typescript // 抽象数据访问逻辑 interface MarketRepository { findAll(filters?: MarketFilters): Promise<Market[]> findById(id: string): Promise<Market | null> create(data: CreateMarketDto): Promise<Market> update(id: string, data: UpdateMarketDto): Promise<Market> delete(id: string): Promise<void> } // Supabase 实现 class SupabaseMarketRepository implements MarketRepository { async findAll(filters?: MarketFilters): Promise<Market[]> { let query = supabase.from('markets').select('*') if (filters?.status) { query = query.eq('status', filters.status) } if (filters?.limit) { query = query.limit(filters.limit) } const { data, error } = await query if (error) throw new Error(error.message) return data } } ``` ### Service 层模式 业务逻辑与数据访问分离。 ```typescript // 业务逻辑与数据访问分离 class MarketService { constructor(private marketRepo: MarketRepository) {} async searchMarkets(query: string, limit: number = 10): Promise<Market[]> { // 业务逻辑 const embedding = await generateEmbedding(query) const results = await this.vectorSearch(embedding, limit) // 获取完整数据 const markets = await this.marketRepo.findByIds(results.map(r => r.id)) // 按相似度排序 return markets.sort((a, b) => { const scoreA = results.find(r => r.id === a.id)?.score || 0 const scoreB = results.find(r => r.id === b.id)?.score || 0 return scoreA - scoreB }) } } ``` ### 中间件模式 ```typescript // 请求/响应处理管道 export function withAuth(handler: NextApiHandler): NextApiHandler { return async (req, res) => { const token = req.headers.authorization?.replace('Bearer ', '') if (!token) { return res.status(401).json({ error: 'Unauthorized' }) } try { const user = await verifyToken(token) req.user = user return handler(req, res) } catch (error) { return res.status(401).json({ error: 'Invalid token' }) } } } // 使用方式 export default withAuth(async (req, res) => { // Handler 可以访问 req.user }) ``` ## 数据库模式 ### 查询优化 ```typescript // 好的写法：只选择需要的列 const { data } = await supabase .from('markets') .select('id, name, status, volume') .eq('status', 'active') .order('volume', { ascending: false }) .limit(10) // 不好的写法：选择所有 const { data } = await supabase .from('markets') .select('*') ``` ### N+1 查询问题预防 ```typescript // 不好的写法：N+1 查询问题 const markets = await getMarkets() for (const market of markets) { market.creator = await getUser(market.creator_id) // N 次查询 } // 好的写法：批量获取 const markets = await getMarkets() const creatorIds = markets.map(m => m.creator_id) const creators = await getUsers(creatorIds) // 1 次查询 const creatorMap = new Map(creators.map(c => [c.id, c])) markets.forEach(market => { market.creator = creatorMap.get(market.creator_id) }) ``` ### 事务模式 ```typescript async function createMarketWithPosition( marketData: CreateMarketDto, positionData: CreatePositionDto ) { // 使用 Supabase 事务 const { data, error } = await supabase.rpc('create_market_with_position', { market_data: marketData, position_data: positionData }) if (error) throw new Error('Transaction failed') return data } ``` ## 缓存策略 ### Redis 缓存层 Cache-Aside 模式：先查缓存，未命中再查数据库，设置合理的过期时间。 ```typescript class CachedMarketRepository implements MarketRepository { constructor( private baseRepo: MarketRepository, private redis: RedisClient ) {} async findById(id: string): Promise<Market | null> { // 先查缓存 const cached = await this.redis.get(`market:${id}`) if (cached) { return JSON.parse(cached) } // 缓存未命中 - 从数据库获取 const market = await this.baseRepo.findById(id) if (market) { // 缓存 5 分钟 await this.redis.setex(`market:${id}`, 300, JSON.stringify(market)) } return market } async invalidateCache(id: string): Promise<void> { await this.redis.del(`market:${id}`) } } ``` ## 错误处理模式 ### 集中式错误处理器 ```typescript class ApiError extends Error { constructor( public statusCode: number, public message: string, public isOperational = true ) { super(message) Object.setPrototypeOf(this, ApiError.prototype) } } export function errorHandler(error: unknown, req: Request): Response { if (error instanceof ApiError) { return NextResponse.json({ success: false, error: error.message }, { status: error.statusCode }) } if (error instanceof z.ZodError) { return NextResponse.json({ success: false, error: 'Validation failed', details: error.errors }, { status: 400 }) } // 记录意外错误 console.error('Unexpected error:', error) return NextResponse.json({ success: false, error: 'Internal server error' }, { status: 500 }) } ``` ### 指数退避重试 ```typescript async function fetchWithRetry<T>( fn: () => Promise<T>, maxRetries = 3 ): Promise<T> { let lastError: Error for (let i = 0; i < maxRetries; i++) { try { return await fn() } catch (error) { lastError = error as Error if (i < maxRetries - 1) { // 指数退避：1s, 2s, 4s const delay = Math.pow(2, i) * 1000 await new Promise(resolve => setTimeout(resolve, delay)) } } } throw lastError! } // 使用方式 const data = await fetchWithRetry(() => fetchFromAPI()) ``` ## 认证与授权 ### JWT 令牌验证 ```typescript import jwt from 'jsonwebtoken' interface JWTPayload { userId: string email: string role: 'admin' | 'user' } export function verifyToken(token: string): JWTPayload { try { const payload = jwt.verify(token, process.env.JWT_SECRET!) as JWTPayload return payload } catch (error) { throw new ApiError(401, 'Invalid token') } } export async function requireAuth(request: Request) { const token = request.headers.get('authorization')?.replace('Bearer ', '') if (!token) { throw new ApiError(401, 'Missing authorization token') } return verifyToken(token) } ``` ### 基于角色的访问控制（RBAC） ```typescript type Permission = 'read' | 'write' | 'delete' | 'admin' interface User { id: string role: 'admin' | 'moderator' | 'user' } const rolePermissions: Record<User['role'], Permission[]> = { admin: ['read', 'write', 'delete', 'admin'], moderator: ['read', 'write', 'delete'], user: ['read', 'write'] } export function hasPermission(user: User, permission: Permission): boolean { return rolePermissions[user.role].includes(permission) } ``` ## 速率限制 ### 简单内存速率限制器 ```typescript class RateLimiter { private requests = new Map<string, number[]>() async checkLimit( identifier: string, maxRequests: number, windowMs: number ): Promise<boolean> { const now = Date.now() const requests = this.requests.get(identifier) || [] // 移除窗口外的旧请求 const recentRequests = requests.filter(time => now - time < windowMs) if (recentRequests.length >= maxRequests) { return false // 超过速率限制 } // 添加当前请求 recentRequests.push(now) this.requests.set(identifier, recentRequests) return true } } ``` ## 日志与监控 ### 结构化日志 ```typescript interface LogContext { userId?: string requestId?: string method?: string path?: string [key: string]: unknown } class Logger { log(level: 'info' | 'warn' | 'error', message: string, context?: LogContext) { const entry = { timestamp: new Date().toISOString(), level, message, ...context } console.log(JSON.stringify(entry)) } info(message: string, context?: LogContext) { this.log('info', message, context) } warn(message: string, context?: LogContext) { this.log('warn', message, context) } error(message: string, error: Error, context?: LogContext) { this.log('error', message, { ...context, error: error.message, stack: error.stack }) } } ``` --- **记住**：后端模式使可扩展、可维护的服务器端应用成为可能。选择适合你复杂度级别的模式。