598 lines
14 KiB
Markdown
598 lines
14 KiB
Markdown
---
|
||
name: backend-patterns
|
||
description: 後端架構模式、API 設計、資料庫優化，以及 Node.js、Express 與 Next.js API 路由的伺服器端最佳實踐。
|
||
---
|
||
|
||
# 後端開發模式 (Backend Development Patterns)
|
||
|
||
用於建置可擴展伺服器端應用程式的後端架構模式與最佳實踐。
|
||
|
||
## 何時啟用
|
||
|
||
- 設計 REST 或 GraphQL API 端點 (Endpoints)
|
||
- 實作儲存庫 (Repository)、服務 (Service) 或控制器 (Controller) 層
|
||
- 優化資料庫查詢 (N+1 問題、索引、連接池)
|
||
- 新增快取機制 (Redis、記憶體內快取、HTTP 快取標頭)
|
||
- 設置背景任務或非同步處理
|
||
- 建立 API 的錯誤處理與驗證結構
|
||
- 撰寫中間件 (Auth、日誌記錄、速率限制)
|
||
|
||
## 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 Pattern)
|
||
|
||
```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>
|
||
}
|
||
|
||
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 Layer Pattern)
|
||
|
||
```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
|
||
})
|
||
}
|
||
|
||
private async vectorSearch(embedding: number[], limit: number) {
|
||
// 向量搜尋實作
|
||
}
|
||
}
|
||
```
|
||
|
||
### 中間件模式 (Middleware Pattern)
|
||
|
||
```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
|
||
// ✅ 推薦 (GOOD)：僅選取所需欄位
|
||
const { data } = await supabase
|
||
.from('markets')
|
||
.select('id, name, status, volume')
|
||
.eq('status', 'active')
|
||
.order('volume', { ascending: false })
|
||
.limit(10)
|
||
|
||
// ❌ 錯誤 (BAD)：選取所有欄位
|
||
const { data } = await supabase
|
||
.from('markets')
|
||
.select('*')
|
||
```
|
||
|
||
### 預防 N+1 查詢問題
|
||
|
||
```typescript
|
||
// ❌ 錯誤 (BAD)：N+1 查詢問題
|
||
const markets = await getMarkets()
|
||
for (const market of markets) {
|
||
market.creator = await getUser(market.creator_id) // 產生 N 次查詢
|
||
}
|
||
|
||
// ✅ 推薦 (GOOD)：批次獲取 (Batch fetch)
|
||
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 Pattern)
|
||
|
||
```typescript
|
||
async function createMarketWithPosition(
|
||
marketData: CreateMarketDto,
|
||
positionData: CreatePositionDto
|
||
) {
|
||
// 使用 Supabase RPC 執行交易
|
||
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
|
||
-- 自動開始交易
|
||
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;
|
||
$$;
|
||
```
|
||
|
||
## 快取策略 (Caching Strategies)
|
||
|
||
### Redis 快取層
|
||
|
||
```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)
|
||
}
|
||
|
||
// 快取失效 (Cache miss) - 從資料庫獲取
|
||
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 模式
|
||
|
||
```typescript
|
||
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
|
||
}
|
||
```
|
||
|
||
## 錯誤處理模式
|
||
|
||
### 集中式錯誤處理器
|
||
|
||
```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 })
|
||
}
|
||
|
||
// 使用方式
|
||
export async function GET(request: Request) {
|
||
try {
|
||
const data = await fetchData()
|
||
return NextResponse.json({ success: true, data })
|
||
} catch (error) {
|
||
return errorHandler(error, request)
|
||
}
|
||
}
|
||
```
|
||
|
||
### 指數退避重試 (Retry with Exponential Backoff)
|
||
|
||
```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 Token 驗證
|
||
|
||
```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)
|
||
}
|
||
|
||
// 在 API 路由中使用
|
||
export async function GET(request: Request) {
|
||
const user = await requireAuth(request)
|
||
|
||
const data = await getDataForUser(user.userId)
|
||
|
||
return NextResponse.json({ success: true, data })
|
||
}
|
||
```
|
||
|
||
### 基於角色的存取控制 (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)
|
||
}
|
||
|
||
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 })
|
||
}
|
||
)
|
||
```
|
||
|
||
## 速率限制 (Rate Limiting)
|
||
|
||
### 簡單的記憶體內速率限制器
|
||
|
||
```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
|
||
}
|
||
}
|
||
|
||
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 req/min
|
||
|
||
if (!allowed) {
|
||
return NextResponse.json({
|
||
error: 'Rate limit exceeded'
|
||
}, { status: 429 })
|
||
}
|
||
|
||
// 繼續處理請求
|
||
}
|
||
```
|
||
|
||
## 背景任務與佇列 (Background Jobs & Queues)
|
||
|
||
### 簡單佇列模式
|
||
|
||
```typescript
|
||
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 })
|
||
|
||
return NextResponse.json({ success: true, message: 'Job queued' })
|
||
}
|
||
```
|
||
|
||
## 日誌記錄與監控
|
||
|
||
### 結構化日誌 (Structured Logging)
|
||
|
||
```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
|
||
})
|
||
}
|
||
}
|
||
|
||
const logger = new Logger()
|
||
|
||
// 使用方式
|
||
export async function GET(request: Request) {
|
||
const requestId = crypto.randomUUID()
|
||
|
||
logger.info('Fetching markets', {
|
||
requestId,
|
||
method: 'GET',
|
||
path: '/api/markets'
|
||
})
|
||
|
||
try {
|
||
const markets = await fetchMarkets()
|
||
return NextResponse.json({ success: true, data: markets })
|
||
} catch (error) {
|
||
logger.error('Failed to fetch markets', error as Error, { requestId })
|
||
return NextResponse.json({ error: 'Internal error' }, { status: 500 })
|
||
}
|
||
}
|
||
```
|
||
|
||
**請記住**：後端模式是建置可擴展、可維護之伺服器端應用程式的關鍵。請根據您的架構複雜程度選擇合適的模式。
|