aiwf 0.3.1 → 0.3.3

package/claude-code/aiwf/ko/personas/backend/best_practices.md

@@ -0,0 +1,766 @@
+# Backend 페르소나 Best Practices
+
+## 개요
+Backend 페르소나는 서버 사이드 로직, 데이터베이스 설계, API 개발에 중점을 둡니다. 확장성, 성능, 데이터 무결성을 최우선으로 고려합니다.
+
+## 핵심 원칙
+
+### 1. API 설계 원칙
+- RESTful 원칙 준수
+- GraphQL 스키마 최적화
+- API 버전 관리
+- 일관된 응답 형식
+
+### 2. 데이터베이스 설계
+```sql
+-- 정규화와 성능의 균형
+CREATE TABLE users (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email VARCHAR(255) UNIQUE NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+-- 인덱스 전략
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_users_created_at ON users(created_at DESC);
+
+-- 파티셔닝 (대용량 테이블)
+CREATE TABLE orders (
+    id BIGSERIAL,
+    user_id UUID REFERENCES users(id),
+    order_date DATE NOT NULL,
+    total_amount DECIMAL(10,2),
+    PRIMARY KEY (id, order_date)
+) PARTITION BY RANGE (order_date);
+```
+
+### 3. 마이크로서비스 아키텍처
+```javascript
+// 서비스 간 통신 패턴
+class OrderService {
+  constructor(eventBus, userService, inventoryService) {
+    this.eventBus = eventBus;
+    this.userService = userService;
+    this.inventoryService = inventoryService;
+  }
+  
+  async createOrder(orderData) {
+    // Saga 패턴으로 분산 트랜잭션 처리
+    const saga = new OrderSaga();
+    
+    try {
+      // 1. 사용자 검증
+      const user = await this.userService.validateUser(orderData.userId);
+      saga.addCompensation(() => this.userService.rollback(user));
+      
+      // 2. 재고 확인 및 예약
+      const reservation = await this.inventoryService.reserve(orderData.items);
+      saga.addCompensation(() => this.inventoryService.release(reservation));
+      
+      // 3. 주문 생성
+      const order = await this.createOrderRecord(orderData);
+      saga.addCompensation(() => this.deleteOrder(order.id));
+      
+      // 4. 이벤트 발행
+      await this.eventBus.publish('order.created', {
+        orderId: order.id,
+        userId: user.id,
+        items: orderData.items
+      });
+      
+      return order;
+    } catch (error) {
+      await saga.compensate();
+      throw error;
+    }
+  }
+}
+```
+
+## API 개발 Best Practices
+
+### RESTful API 설계
+```javascript
+// Express.js 라우터
+class UserController {
+  // GET /api/v1/users?page=1&limit=20&sort=created_at:desc
+  async getUsers(req, res) {
+    const { page = 1, limit = 20, sort, filter } = req.query;
+    
+    try {
+      const users = await this.userService.findAll({
+        pagination: { page, limit },
+        sorting: this.parseSortParam(sort),
+        filters: this.parseFilterParam(filter)
+      });
+      
+      res.json({
+        success: true,
+        data: users,
+        meta: {
+          page: parseInt(page),
+          limit: parseInt(limit),
+          total: users.total,
+          totalPages: Math.ceil(users.total / limit)
+        }
+      });
+    } catch (error) {
+      this.handleError(error, res);
+    }
+  }
+  
+  // POST /api/v1/users
+  async createUser(req, res) {
+    try {
+      // 입력 검증
+      const validatedData = await this.validator.validate(req.body, UserSchema);
+      
+      // 비즈니스 로직
+      const user = await this.userService.create(validatedData);
+      
+      // 201 Created with Location header
+      res.status(201)
+         .location(`/api/v1/users/${user.id}`)
+         .json({
+           success: true,
+           data: user
+         });
+    } catch (error) {
+      this.handleError(error, res);
+    }
+  }
+  
+  // Error handling
+  handleError(error, res) {
+    if (error instanceof ValidationError) {
+      return res.status(400).json({
+        success: false,
+        error: {
+          code: 'VALIDATION_ERROR',
+          message: error.message,
+          details: error.details
+        }
+      });
+    }
+    
+    if (error instanceof NotFoundError) {
+      return res.status(404).json({
+        success: false,
+        error: {
+          code: 'NOT_FOUND',
+          message: error.message
+        }
+      });
+    }
+    
+    // 500 Internal Server Error
+    console.error('Unexpected error:', error);
+    res.status(500).json({
+      success: false,
+      error: {
+        code: 'INTERNAL_ERROR',
+        message: 'An unexpected error occurred'
+      }
+    });
+  }
+}
+```
+
+### GraphQL 스키마 설계
+```graphql
+# Schema Definition
+type User {
+  id: ID!
+  email: String!
+  profile: Profile!
+  orders(
+    first: Int = 10
+    after: String
+    filter: OrderFilter
+  ): OrderConnection!
+  createdAt: DateTime!
+  updatedAt: DateTime!
+}
+
+type Profile {
+  firstName: String!
+  lastName: String!
+  avatar: String
+  preferences: UserPreferences!
+}
+
+# Pagination using Relay specification
+type OrderConnection {
+  edges: [OrderEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type OrderEdge {
+  node: Order!
+  cursor: String!
+}
+
+# Input types
+input CreateUserInput {
+  email: String!
+  password: String!
+  profile: ProfileInput!
+}
+
+# Queries
+type Query {
+  user(id: ID!): User
+  users(
+    first: Int
+    after: String
+    filter: UserFilter
+    orderBy: UserOrderBy
+  ): UserConnection!
+  me: User @auth
+}
+
+# Mutations
+type Mutation {
+  createUser(input: CreateUserInput!): CreateUserPayload!
+  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
+  deleteUser(id: ID!): DeleteUserPayload!
+}
+
+# Subscriptions
+type Subscription {
+  userUpdated(userId: ID!): User!
+  orderCreated(userId: ID!): Order!
+}
+```
+
+## 데이터베이스 최적화
+
+### 쿼리 최적화
+```javascript
+// Query Builder Pattern
+class UserRepository {
+  constructor(db) {
+    this.db = db;
+  }
+  
+  // N+1 문제 방지
+  async findWithOrders(userId) {
+    const query = `
+      SELECT 
+        u.id, u.email, u.created_at,
+        o.id as order_id, o.total_amount, o.order_date,
+        oi.product_id, oi.quantity, oi.price
+      FROM users u
+      LEFT JOIN orders o ON u.id = o.user_id
+      LEFT JOIN order_items oi ON o.id = oi.order_id
+      WHERE u.id = $1
+      ORDER BY o.order_date DESC
+    `;
+    
+    const result = await this.db.query(query, [userId]);
+    return this.mapResultToUser(result.rows);
+  }
+  
+  // Batch loading
+  async findByIds(userIds) {
+    if (userIds.length === 0) return [];
+    
+    const query = `
+      SELECT * FROM users 
+      WHERE id = ANY($1::uuid[])
+    `;
+    
+    const result = await this.db.query(query, [userIds]);
+    
+    // 순서 보장
+    const userMap = new Map(
+      result.rows.map(row => [row.id, row])
+    );
+    
+    return userIds.map(id => userMap.get(id)).filter(Boolean);
+  }
+  
+  // 동적 쿼리 빌더
+  async search(criteria) {
+    let query = 'SELECT * FROM users WHERE 1=1';
+    const params = [];
+    let paramIndex = 1;
+    
+    if (criteria.email) {
+      query += ` AND email ILIKE $${paramIndex}`;
+      params.push(`%${criteria.email}%`);
+      paramIndex++;
+    }
+    
+    if (criteria.createdAfter) {
+      query += ` AND created_at >= $${paramIndex}`;
+      params.push(criteria.createdAfter);
+      paramIndex++;
+    }
+    
+    if (criteria.sortBy) {
+      const validColumns = ['email', 'created_at'];
+      if (validColumns.includes(criteria.sortBy)) {
+        query += ` ORDER BY ${criteria.sortBy} ${
+          criteria.sortOrder === 'desc' ? 'DESC' : 'ASC'
+        }`;
+      }
+    }
+    
+    query += ` LIMIT $${paramIndex} OFFSET $${paramIndex + 1}`;
+    params.push(criteria.limit || 20, criteria.offset || 0);
+    
+    return this.db.query(query, params);
+  }
+}
+```
+
+### 캐싱 전략
+```javascript
+// Redis 캐싱 레이어
+class CacheService {
+  constructor(redis, ttl = 3600) {
+    this.redis = redis;
+    this.ttl = ttl;
+  }
+  
+  // Cache-Aside Pattern
+  async get(key, fetchFn) {
+    // 1. 캐시 확인
+    const cached = await this.redis.get(key);
+    if (cached) {
+      return JSON.parse(cached);
+    }
+    
+    // 2. 캐시 미스 시 데이터 조회
+    const data = await fetchFn();
+    
+    // 3. 캐시 저장
+    await this.redis.setex(
+      key,
+      this.ttl,
+      JSON.stringify(data)
+    );
+    
+    return data;
+  }
+  
+  // Write-Through Pattern
+  async set(key, data, ttl = this.ttl) {
+    await this.redis.setex(
+      key,
+      ttl,
+      JSON.stringify(data)
+    );
+    return data;
+  }
+  
+  // Cache Invalidation
+  async invalidate(pattern) {
+    const keys = await this.redis.keys(pattern);
+    if (keys.length > 0) {
+      await this.redis.del(...keys);
+    }
+  }
+  
+  // Distributed Lock (분산 환경)
+  async acquireLock(lockKey, ttl = 10) {
+    const identifier = uuidv4();
+    const result = await this.redis.set(
+      `lock:${lockKey}`,
+      identifier,
+      'NX',
+      'EX',
+      ttl
+    );
+    
+    return result === 'OK' ? identifier : null;
+  }
+  
+  async releaseLock(lockKey, identifier) {
+    const script = `
+      if redis.call("get", KEYS[1]) == ARGV[1] then
+        return redis.call("del", KEYS[1])
+      else
+        return 0
+      end
+    `;
+    
+    return this.redis.eval(
+      script,
+      1,
+      `lock:${lockKey}`,
+      identifier
+    );
+  }
+}
+```
+
+## 메시지 큐와 이벤트 처리
+
+### RabbitMQ 패턴
+```javascript
+// Publisher/Subscriber Pattern
+class EventPublisher {
+  constructor(channel) {
+    this.channel = channel;
+  }
+  
+  async publish(exchange, routingKey, message) {
+    const messageBuffer = Buffer.from(JSON.stringify({
+      ...message,
+      timestamp: new Date().toISOString(),
+      messageId: uuidv4()
+    }));
+    
+    await this.channel.publish(
+      exchange,
+      routingKey,
+      messageBuffer,
+      {
+        persistent: true,
+        contentType: 'application/json',
+        headers: {
+          'x-retry-count': 0
+        }
+      }
+    );
+  }
+}
+
+// Consumer with Error Handling
+class EventConsumer {
+  constructor(channel, options = {}) {
+    this.channel = channel;
+    this.maxRetries = options.maxRetries || 3;
+  }
+  
+  async consume(queue, handler) {
+    await this.channel.consume(queue, async (msg) => {
+      if (!msg) return;
+      
+      try {
+        const content = JSON.parse(msg.content.toString());
+        await handler(content);
+        
+        // Acknowledge message
+        this.channel.ack(msg);
+      } catch (error) {
+        console.error('Error processing message:', error);
+        
+        // Retry logic
+        const retryCount = (msg.properties.headers['x-retry-count'] || 0) + 1;
+        
+        if (retryCount <= this.maxRetries) {
+          // Requeue with delay
+          setTimeout(() => {
+            this.channel.sendToQueue(
+              queue,
+              msg.content,
+              {
+                ...msg.properties,
+                headers: {
+                  ...msg.properties.headers,
+                  'x-retry-count': retryCount
+                }
+              }
+            );
+          }, Math.pow(2, retryCount) * 1000); // Exponential backoff
+        } else {
+          // Send to DLQ
+          await this.sendToDeadLetter(msg, error);
+        }
+        
+        // Reject without requeue
+        this.channel.nack(msg, false, false);
+      }
+    });
+  }
+  
+  async sendToDeadLetter(msg, error) {
+    const dlq = `${msg.fields.routingKey}.dlq`;
+    await this.channel.sendToQueue(
+      dlq,
+      msg.content,
+      {
+        headers: {
+          'x-death-reason': error.message,
+          'x-original-queue': msg.fields.routingKey
+        }
+      }
+    );
+  }
+}
+```
+
+## 보안 구현
+
+### 인증/인가 미들웨어
+```javascript
+// JWT Authentication
+class AuthMiddleware {
+  constructor(jwtService, userService) {
+    this.jwtService = jwtService;
+    this.userService = userService;
+  }
+  
+  authenticate() {
+    return async (req, res, next) => {
+      try {
+        const token = this.extractToken(req);
+        if (!token) {
+          return res.status(401).json({
+            error: 'No authentication token provided'
+          });
+        }
+        
+        const payload = await this.jwtService.verify(token);
+        
+        // Token blacklist check
+        if (await this.isTokenBlacklisted(payload.jti)) {
+          return res.status(401).json({
+            error: 'Token has been revoked'
+          });
+        }
+        
+        req.user = await this.userService.findById(payload.sub);
+        next();
+      } catch (error) {
+        if (error.name === 'TokenExpiredError') {
+          return res.status(401).json({
+            error: 'Token has expired'
+          });
+        }
+        
+        return res.status(401).json({
+          error: 'Invalid authentication token'
+        });
+      }
+    };
+  }
+  
+  authorize(...roles) {
+    return (req, res, next) => {
+      if (!req.user) {
+        return res.status(401).json({
+          error: 'Authentication required'
+        });
+      }
+      
+      if (roles.length > 0 && !roles.includes(req.user.role)) {
+        return res.status(403).json({
+          error: 'Insufficient permissions'
+        });
+      }
+      
+      next();
+    };
+  }
+  
+  extractToken(req) {
+    const authHeader = req.headers.authorization;
+    if (authHeader && authHeader.startsWith('Bearer ')) {
+      return authHeader.substring(7);
+    }
+    
+    return req.cookies?.accessToken;
+  }
+}
+```
+
+## 테스팅 전략
+
+### 단위 테스트
+```javascript
+describe('UserService', () => {
+  let userService;
+  let userRepository;
+  let emailService;
+  
+  beforeEach(() => {
+    userRepository = {
+      findByEmail: jest.fn(),
+      create: jest.fn(),
+      update: jest.fn()
+    };
+    
+    emailService = {
+      sendWelcomeEmail: jest.fn()
+    };
+    
+    userService = new UserService(userRepository, emailService);
+  });
+  
+  describe('createUser', () => {
+    it('should create user with hashed password', async () => {
+      const userData = {
+        email: 'test@example.com',
+        password: 'password123'
+      };
+      
+      userRepository.findByEmail.mockResolvedValue(null);
+      userRepository.create.mockResolvedValue({
+        id: 'user-123',
+        ...userData,
+        password: 'hashed-password'
+      });
+      
+      const user = await userService.createUser(userData);
+      
+      expect(userRepository.findByEmail).toHaveBeenCalledWith(userData.email);
+      expect(userRepository.create).toHaveBeenCalledWith({
+        email: userData.email,
+        password: expect.stringMatching(/^\$2[aby]\$/)
+      });
+      expect(emailService.sendWelcomeEmail).toHaveBeenCalledWith(userData.email);
+      expect(user).not.toHaveProperty('password');
+    });
+    
+    it('should throw error if email already exists', async () => {
+      userRepository.findByEmail.mockResolvedValue({ id: 'existing-user' });
+      
+      await expect(
+        userService.createUser({ email: 'test@example.com', password: 'pass' })
+      ).rejects.toThrow('Email already registered');
+    });
+  });
+});
+```
+
+### 통합 테스트
+```javascript
+describe('API Integration Tests', () => {
+  let app;
+  let db;
+  
+  beforeAll(async () => {
+    // Test database setup
+    db = await createTestDatabase();
+    app = createApp(db);
+  });
+  
+  afterAll(async () => {
+    await db.close();
+  });
+  
+  describe('POST /api/users', () => {
+    it('should create user and return 201', async () => {
+      const response = await request(app)
+        .post('/api/users')
+        .send({
+          email: 'newuser@example.com',
+          password: 'SecurePass123!',
+          profile: {
+            firstName: 'John',
+            lastName: 'Doe'
+          }
+        });
+      
+      expect(response.status).toBe(201);
+      expect(response.headers.location).toMatch(/\/api\/users\/[\w-]+/);
+      expect(response.body).toMatchObject({
+        success: true,
+        data: {
+          email: 'newuser@example.com',
+          profile: {
+            firstName: 'John',
+            lastName: 'Doe'
+          }
+        }
+      });
+      
+      // Verify database
+      const user = await db.query(
+        'SELECT * FROM users WHERE email = $1',
+        ['newuser@example.com']
+      );
+      expect(user.rows).toHaveLength(1);
+    });
+  });
+});
+```
+
+## 모니터링과 로깅
+
+### 구조화된 로깅
+```javascript
+class Logger {
+  constructor(service) {
+    this.service = service;
+    this.winston = winston.createLogger({
+      format: winston.format.combine(
+        winston.format.timestamp(),
+        winston.format.errors({ stack: true }),
+        winston.format.json()
+      ),
+      defaultMeta: { service },
+      transports: [
+        new winston.transports.Console({
+          format: winston.format.simple()
+        }),
+        new winston.transports.File({
+          filename: 'error.log',
+          level: 'error'
+        }),
+        new winston.transports.File({
+          filename: 'combined.log'
+        })
+      ]
+    });
+  }
+  
+  log(level, message, meta = {}) {
+    this.winston.log({
+      level,
+      message,
+      ...meta,
+      timestamp: new Date().toISOString()
+    });
+  }
+  
+  // Request logging middleware
+  requestLogger() {
+    return (req, res, next) => {
+      const start = Date.now();
+      
+      res.on('finish', () => {
+        const duration = Date.now() - start;
+        
+        this.log('info', 'HTTP Request', {
+          method: req.method,
+          path: req.path,
+          statusCode: res.statusCode,
+          duration,
+          ip: req.ip,
+          userAgent: req.get('user-agent'),
+          userId: req.user?.id
+        });
+      });
+      
+      next();
+    };
+  }
+}
+```
+
+## 배포 전 체크리스트
+
+### 성능
+- [ ] 데이터베이스 인덱스 최적화
+- [ ] N+1 쿼리 제거
+- [ ] 캐싱 전략 구현
+- [ ] 비동기 처리 적용
+
+### 보안
+- [ ] 환경 변수로 민감 정보 관리
+- [ ] SQL Injection 방지
+- [ ] Rate Limiting 설정
+- [ ] CORS 정책 구성
+
+### 안정성
+- [ ] 에러 처리 및 복구 메커니즘
+- [ ] 서킷 브레이커 패턴
+- [ ] 헬스체크 엔드포인트
+- [ ] 우아한 종료(Graceful Shutdown)