backend-dev-guidelines

バックエンド開発ガイドライン

目的

モダンな Node.js/Express/TypeScript のパターンを用いて、バックエンドのマイクロサービス（blog-api、auth-service、notifications-service）全体で一貫性とベストプラクティスを確立します。

このスキルを使用するタイミング

以下の作業を行うと自動的に有効になります:

• ルート、エンドポイント、API の作成や変更
• コントローラー、サービス、リポジトリの構築
• ミドルウェア（認証、バリデーション、エラーハンドリング）の実装
• Prisma を使用したデータベース操作
• Sentry によるエラートラッキング
• Zod による入力バリデーション
• 設定管理
• バックエンドのテストとリファクタリング

---

クイックスタート

新規バックエンド機能のチェックリスト

• ルート: 明確な定義とし、コントローラーに処理を委譲する
• コントローラー: BaseController を継承する
• サービス: DI を用いてビジネスロジックを実装する
• リポジトリ: データベースアクセス（複雑な場合）
• バリデーション: Zod スキーマ
• Sentry: エラートラッキング
• テスト: ユニットテストと統合テスト
• 設定: unifiedConfig を使用する

新規マイクロサービスのチェックリスト

• ディレクトリ構成（architecture-overview.md を参照）
• Sentry 用の instrument.ts
• unifiedConfig のセットアップ
• BaseController クラス
• ミドルウェアスタック
• エラーバウンダリ
• テストフレームワーク

---

アーキテクチャの概要

レイヤー構造のアーキテクチャ

HTTP Request
    ↓
Routes (routing only)
    ↓
Controllers (request handling)
    ↓
Services (business logic)
    ↓
Repositories (data access)
    ↓
Database (Prisma)

主要原則: 各レイヤーは責務を 1 つだけ持つ。

詳細は architecture-overview.md を参照してください。

---

ディレクトリ構成

service/src/
├── config/              # UnifiedConfig
├── controllers/         # Request handlers
├── services/            # Business logic
├── repositories/        # Data access
├── routes/              # Route definitions
├── middleware/          # Express middleware
├── types/               # TypeScript types
├── validators/          # Zod schemas
├── utils/               # Utilities
├── tests/               # Tests
├── instrument.ts        # Sentry (FIRST IMPORT)
├── app.ts               # Express setup
└── server.ts            # HTTP server

命名規則:

• コントローラー: PascalCase - UserController.ts
• サービス: camelCase - userService.ts
• ルート: camelCase + Routes - userRoutes.ts
• リポジトリ: PascalCase + Repository - UserRepository.ts

---

コア原則（7 つの主要ルール）

1. ルートはルーティングのみ、コントローラーが制御する

// ❌ NEVER: Business logic in routes
router.post('/submit', async (req, res) => {
    // 200 lines of logic
});

// ✅ ALWAYS: Delegate to controller
router.post('/submit', (req, res) => controller.submit(req, res));

2. すべてのコントローラーは BaseController を継承する

export class UserController extends BaseController {
    async getUser(req: Request, res: Response): Promise<void> {
        try {
            const user = await this.userService.findById(req.params.id);
            this.handleSuccess(res, user);
        } catch (error) {
            this.handleError(error, res, 'getUser');
        }
    }
}

3. すべてのエラーを Sentry に送る

try {
    await operation();
} catch (error) {
    Sentry.captureException(error);
    throw error;
}

4. unifiedConfig を使用し、process.env は決して使用しない

// ❌ NEVER
const timeout = process.env.TIMEOUT_MS;

// ✅ ALWAYS
import { config } from './config/unifiedConfig';
const timeout = config.timeouts.default;

5. すべての入力を Zod でバリデーションする

const schema = z.object({ email: z.string().email() });
const validated = schema.parse(req.body);

6. データアクセスにはリポジトリパターンを使用する

// Service → Repository → Database
const users = await userRepository.findActive();

7. 包括的なテストが必須

describe('UserService', () => {
    it('should create user', async () => {
        expect(user).toBeDefined();
    });
});

---

共通インポート

// Express
import express, { Request, Response, NextFunction, Router } from 'express';

// Validation
import { z } from 'zod';

// Database
import { PrismaClient } from '@prisma/client';
import type { Prisma } from '@prisma/client';

// Sentry
import * as Sentry from '@sentry/node';

// Config
import { config } from './config/unifiedConfig';

// Middleware
import { SSOMiddlewareClient } from './middleware/SSOMiddleware';
import { asyncErrorWrapper } from './middleware/errorBoundary';

---

クイックリファレンス

HTTP ステータスコード

コード	用途
200	成功
201	作成済み
400	不正なリクエスト
401	未認証
403	アクセス禁止
404	見つからない
500	サーバーエラー

サービステンプレート

Blog API（✅ 成熟）- REST API のテンプレートとして使用 Auth Service（✅ 成熟）- 認証パターンのテンプレートとして使用

---

避けるべきアンチパターン

❌ ルート内のビジネスロジック ❌ process.env の直接使用 ❌ エラーハンドリングの欠落 ❌ 入力バリデーションなし ❌ あらゆる場所での Prisma の直接使用 ❌ Sentry の代わりに console.log を使用

---

ナビゲーションガイド

やりたいこと	参照先
アーキテクチャを理解する	architecture-overview.md
ルート/コントローラーを作成する	routing-and-controllers.md
ビジネスロジックを整理する	services-and-repositories.md
入力をバリデーションする	validation-patterns.md
エラートラッキングを追加する	sentry-and-monitoring.md
ミドルウェアを作成する	middleware-guide.md
データベースアクセス	database-patterns.md
設定を管理する	configuration.md
非同期処理とエラーを扱う	async-and-errors.md
テストを書く	testing-guide.md
例を見る	complete-examples.md

---

リソースファイル

architecture-overview.md

レイヤー構造のアーキテクチャ、リクエストのライフサイクル、関心の分離

routing-and-controllers.md

ルート定義、BaseController、エラーハンドリング、例

services-and-repositories.md

サービスパターン、DI、リポジトリパターン、キャッシュ

validation-patterns.md

Zod スキーマ、バリデーション、DTO パターン

sentry-and-monitoring.md

Sentry の初期化、エラーキャプチャ、パフォーマンスモニタリング

middleware-guide.md

認証、監査、エラーバウンダリ、AsyncLocalStorage

database-patterns.md

PrismaService、リポジトリ、トランザクション、最適化

configuration.md

UnifiedConfig、環境ごとの設定、シークレット

async-and-errors.md

非同期パターン、カスタムエラー、asyncErrorWrapper

testing-guide.md

ユニットテスト・インテグレーションテスト、モック、カバレッジ

complete-examples.md

完全な例、リファクタリングガイド

---

関連スキル

• database-verification - カラム名とスキーマの整合性を検証
• error-tracking - Sentry 統合パターン
• skill-developer - スキルの作成と管理のためのメタスキル

---

スキルステータス: COMPLETE ✅ 行数: < 500 ✅ 段階的開示: 11 個のリソースファイル ✅