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

目的

モダン 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 リクエスト
    ↓
ルート (ルーティングのみ)
    ↓
コントローラー (リクエスト処理)
    ↓
サービス (ビジネスロジック)
    ↓
リポジトリ (データアクセス)
    ↓
データベース (Prisma)

重要原則: 各レイヤーは 1 つの責務を持ちます。

完全な詳細については architecture-overview.md を参照してください。

---

ディレクトリ構造

service/src/
├── config/              # UnifiedConfig
├── controllers/         # リクエストハンドラー
├── services/            # ビジネスロジック
├── repositories/        # データアクセス
├── routes/              # ルート定義
├── middleware/          # Express ミドルウェア
├── types/               # TypeScript 型
├── validators/          # Zod スキーマ
├── utils/               # ユーティリティ
├── tests/               # テスト
├── instrument.ts        # Sentry (最初のインポート)
├── app.ts               # Express セットアップ
└── server.ts            # HTTP サーバー

命名規則:

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

---

コア原則 (7 つの重要ルール)

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

// ❌ 禁止: ルートにビジネスロジック
router.post('/submit', async (req, res) => {
    // 200 行のロジック
});

// ✅ 必須: コントローラーへ委譲
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 を直接使用しない

// ❌ 禁止
const timeout = process.env.TIMEOUT_MS;

// ✅ 必須
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. データアクセスにはリポジトリパターンを使用

// サービス → リポジトリ → データベース
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';

// 検証
import { z } from 'zod';

// データベース
import { PrismaClient } from '@prisma/client';
import type { Prisma } from '@prisma/client';

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

// 設定
import { config } from './config/unifiedConfig';

// ミドルウェア
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 - スキル作成と管理のためのメタスキル

---

スキルステータス: 完了 ✅ 行数: < 500 ✅ 段階的情報開示: 11 リソースファイル ✅