backend-patterns

name backend-patterns description Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes. 後端開發模式 用於可擴展伺服器端應用程式的後端架構模式和最佳實務。 API 設計模式 RESTful API 結構 // PASS: 基於資源的 URL GET /api/markets # 列出資源 GET /api/markets/:id # 取得單一資源 POST /api/markets # 建立資源 PUT /api/markets/:id # 替換資源 PATCH /api/markets/:id # 更新資源 DELETE /api/markets/:id # 刪除資源 // PASS: 用於過濾、排序、分頁的查詢參數 GET /api/markets?status=active&sort=volume&limit= 20 &offset= 0 Repository 模式 // 抽象資料存取邏輯 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 > } 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 層模式 // 業務邏輯與資料存取分離 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 }) } private async vectorSearch ( embedding : number [], limit : number ) { // 向量搜尋實作 } } Middleware 模式 // 請求/回應處理流水線 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 }) 資料庫模式 查詢優化 // PASS: 良好：只選擇需要的欄位 const { data } = await supabase . from ( 'markets' ) . select ( 'id, name, status, volume' ) . eq ( 'status' , 'active' ) . order ( 'volume' , { ascending : false }) . limit ( 10 ) // FAIL: 不良：選擇所有欄位 const { data } = await supabase . from ( 'markets' ) . select ( '*' ) N+1 查詢問題預防 // FAIL: 不良：N+1 查詢問題 const markets = await getMarkets () for ( const market of markets) { market. creator = await getUser (market. creator_id ) // N 次查詢 } // PASS: 良好：批次取得 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 ) }) Transaction 模式 async function createMarketWithPosition ( marketData : CreateMarketDto , positionData : CreatePositionDto ) { // 使用 Supabase transaction 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 } // Supabase 中的 SQL 函式 CREATE OR REPLACE FUNCTION create_market_with_position ( market_data jsonb, position_data jsonb ) RETURNS jsonb LANGUAGE plpgsql AS $$ BEGIN -- 自動開始 transaction INSERT INTO markets VALUES (market_data); INSERT INTO positions VALUES (position_data); RETURN jsonb_build_object ( 'success' , true ); EXCEPTION WHEN OTHERS THEN -- 自動 rollback RETURN jsonb_build_object ( 'success' , false , 'error' , SQLERRM ); END ; $$; 快取策略 Redis 快取層 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} ` ) } } Cache-Aside 模式 async function getMarketWithCache ( id : string ): Promise < Market > { const cacheKey = `market: ${id} ` // 嘗試快取 const cached = await redis. get (cacheKey) if (cached) return JSON . parse (cached) // 快取未命中 - 從資料庫取得 const market = await db. markets . findUnique ({ where : { id } }) if (!market) throw new Error ( 'Market not found' ) // 更新快取 await redis. setex (cacheKey, 300 , JSON . stringify (market)) return market } 錯誤處理模式 集中式錯誤處理器 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 }) } // 使用方式 export async function GET ( request : Request ) { try { const data = await fetchData () return NextResponse . json ({ success : true , data }) } catch (error) { return errorHandler (error, request) } } 指數退避重試 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 Token 驗證 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) } // 在 API 路由中使用 export async function GET ( request : Request ) { const user = await requireAuth (request) const data = await getDataForUser (user. userId ) return NextResponse . json ({ success : true , data }) } 基於角色的存取控制 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) } export function requirePermission ( permission : Permission ) { return ( handler : (request: Request, user: User) => Promise < Response > ) => { return async ( request : Request ) => { const user = await requireAuth (request) if (! hasPermission (user, permission)) { throw new ApiError ( 403 , 'Insufficient permissions' ) } return handler (request, user) } } } // 使用方式 - HOF 包裝 handler export const DELETE = requirePermission ( 'delete' )( async ( request : Request , user : User ) => { // Handler 接收已驗證且具有已驗證權限的使用者 return new Response ( 'Deleted' , { status : 200 }) } ) 速率限制 簡單的記憶體速率限制器 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 } } const limiter = new RateLimiter () export async function GET ( request : Request ) { const ip = request. headers . get ( 'x-forwarded-for' ) || 'unknown' const allowed = await limiter. checkLimit (ip, 100 , 60000 ) // 100 請求/分鐘 if (!allowed) { return NextResponse . json ({ error : 'Rate limit exceeded' }, { status : 429 }) } // 繼續處理請求 } 背景任務與佇列 簡單佇列模式 class JobQueue <T> { private queue : T[] = [] private processing = false async add ( job : T): Promise < void > { this . queue . push (job) if (! this . processing ) { this . process () } } private async process (): Promise < void > { this . processing = true while ( this . queue . length > 0 ) { const job = this . queue . shift ()! try { await this . execute (job) } catch (error) { console . error ( 'Job failed:' , error) } } this . processing = false } private async execute ( job : T): Promise < void > { // 任務執行邏輯 } } // 用於索引市場的使用範例 interface IndexJob { marketId : string } const indexQueue = new JobQueue < IndexJob >() export async function POST ( request : Request ) { const { marketId } = await request. json () // 加入佇列而非阻塞 await indexQueue. add ({ marketId })