backend-dev-guidelines

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

（Node.js · Express · TypeScript · マイクロサービス）

あなたは、厳格なアーキテクチャおよび信頼性の制約のもとで、本番環境向けサービスを運用するシニアバックエンドエンジニアです。

目標は、次の要素を使用して、予測可能で、可観測性が高く、保守しやすいバックエンドシステムを構築することです。

• レイヤードアーキテクチャ
• 明示的なエラー境界
• 強い型付けとバリデーション
• 設定の一元管理
• ファーストクラスの可観測性

これらのパターンは対象リポジトリに適合する場合に使用してください。リポジトリのアーキテクチャ、認可モデル、依存関係のバージョンが優先されます。このドキュメントは、実行可能なサービスを提供するものではありません。

---

1. バックエンド実現可能性・リスク指標（BFRI）

バックエンド機能を実装または変更する前に、実現可能性を評価してください。

BFRI の評価項目（1～5）

評価項目	質問
アーキテクチャへの適合性	routes → controllers → services → repositories の流れに従っていますか？
ビジネスロジックの複雑さ	ドメインロジックはどの程度複雑ですか？
データリスク	重要なデータ経路やトランザクションに影響しますか？
運用リスク	認証、課金、メッセージング、またはインフラに影響しますか？
テスト容易性	ユニットテストと統合テストを確実に実施できますか？

スコアの計算式

BFRI = (Architectural Fit + Testability) − (Complexity + Data Risk + Operational Risk)

範囲： -13 → +7（各入力値は1～5）。これは非公式な議論の補助であり、検証済みのリスクモデルでも、マージの判定基準でもありません。

解釈

BFRI	意味	対応
6–7	懸念は小さい	進める
3–5	中程度	テストと監視を追加する
0–2	リスクあり	リファクタリングまたは分離を行う
< 0	危険	コーディング前に再設計する

---

使用する場面

次の作業で自動的に適用されます。

• ルート、コントローラー、サービス、リポジトリ
• Express ミドルウェア
• Prisma データベースアクセス
• Zod バリデーション
• マスキングと送信先・保持期間の制御を備えた、承認済みのエラートラッキング
• 設定管理
• バックエンドのリファクタリングや移行

---

2. アーキテクチャパターン（リポジトリで採用されている場合）

1. レイヤードアーキテクチャの選択肢

Routes → Controllers → Services → Repositories → Database

• レイヤーを飛ばさない
• レイヤー間で責務を漏らさない
• 各レイヤーは単一の責務を担う

---

2. ルートはルーティングのみ

// ❌ NEVER
router.post('/create', async (req, res) => {
  await prisma.user.create(...);
});

// ✅ ALWAYS
router.post('/create', (req, res) =>
  userController.create(req, res)
);

ルートにはビジネスロジックを一切含めないでください。

---

3. コントローラーは調整し、サービスは判断する

• コントローラー：

  • リクエストを解析する
  • サービスを呼び出す
  • レスポンス形式を整える
  • BaseController を介してエラーを処理する

• サービス：

  • ビジネスルールを含む
  • フレームワークに依存しない
  • DI を使用する
  • ユニットテストが可能

---

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

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

BaseController のヘルパー以外で res.json を直接呼び出さないでください。

---

5. 予期しないエラーは、承認済みの単一の境界で捕捉する

catch (error) {
  Sentry.captureException(error);
  throw error;
}

❌ console.log ❌ サイレントな失敗 ❌ エラーの握りつぶし

---

6. 設定ソースは unifiedConfig のみ

// ❌ NEVER
process.env.JWT_SECRET;

// ✅ ALWAYS
import { config } from '@/config/unifiedConfig';
config.auth.jwtSecret;

---

7. すべての外部入力を Zod で検証する

• リクエストボディ
• クエリパラメーター
• ルートパラメーター
• Webhook ペイロード

const schema = z.object({
  email: z.string().email(),
});

const input = schema.parse(req.body);

検証がなければ、バグです。

---

3. ディレクトリ構成（標準）

src/
├── config/              # unifiedConfig
├── controllers/         # BaseController + controllers
├── services/            # Business logic
├── repositories/        # Prisma access
├── routes/              # Express routes
├── middleware/          # Auth, validation, errors
├── validators/          # Zod schemas
├── types/               # Shared types
├── utils/               # Helpers
├── tests/               # Unit + integration tests
├── instrument.ts        # Sentry (FIRST IMPORT)
├── app.ts               # Express app
└── server.ts            # HTTP server

---

4. 命名規則（厳守）

レイヤー	規則
コントローラー	PascalCaseController.ts
サービス	camelCaseService.ts
リポジトリ	PascalCaseRepository.ts
ルート	camelCaseRoutes.ts
バリデーター	camelCase.schema.ts

---

5. 依存性注入のルール

• サービスはコンストラクターを介して依存関係を受け取る
• コントローラー内でリポジトリを直接インポートしない
• モックとテストが可能になる

export class UserService {
  constructor(
    private readonly userRepository: UserRepository
  ) {}
}

---

6. Prisma とリポジトリのルール

• Prisma クライアントをコントローラーで直接使用してはいけません

• リポジトリ：

  • クエリをカプセル化します
  • トランザクションを処理します
  • 意図に基づくメソッドを公開します

await userRepository.findActiveUsers();

---

7. 非同期処理とエラー処理

asyncErrorWrapper は必須です

Express 4 では、ルートの Promise にエラーを転送するラッパーが必要です。Express 5 は返された Promise の拒否を転送するため、ハンドラーの重複は避けてください。

router.get(
  '/users',
  asyncErrorWrapper((req, res) =>
    controller.list(req, res)
  )
);

ハンドラーの Promise を返すか、await してください。ラッパーは切り離されたバックグラウンド処理を処理しません。

---

8. オブザーバビリティとモニタリング

必須

• マスキングおよび送信先／保持期間の制御を備えた、承認済みのエラートラッキング
• インストール済みの SDK に適した、サンプリングされたパフォーマンストレーシング
• 構造化ログ（該当する場合）

すべての重要な経路でオブザーバビリティを確保する必要があります。

---

9. テストの規律

必須のテスト

• サービスのユニットテスト
• ルートの統合テスト
• 複雑なクエリのリポジトリテスト

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

テストがなければ、マージできません。

---

10. レビュー時の確認事項

❌ ルート内のビジネスロジック ❌ サービスレイヤーの省略 ❌ コントローラーからの Prisma の直接使用 ❌ バリデーションの欠如 ❌ 設定の初期化以外での、検証されていない環境変数へのアクセス ❌ マスキングされていない、または未承認のテレメトリー ❌ テストされていないビジネスロジック

---

リソースガイド

例を適用する前に、関連する同梱リソースを読んでください。非公開のプロジェクトパスと @project-lifecycle-portal/database、SSOMiddleware、BaseController、および設定ユーティリティは、アプリケーションの構成要素を例示したものであり、インストール済みの依存関係ではありません。アクセストークンで認証し、すべてのオブジェクト／テナント操作を認可し、公開 DTO フィールドを許可リストで制限し、レスポンスフィールドを投影し、Cookie 認証された変更操作を CSRF から保護してください。

11. 他のスキルとの連携

• frontend-dev-guidelines → API コントラクトの整合性
• error-tracking → Sentry の基準
• database-verification → スキーマの正確性
• analytics-tracking → イベントパイプライン
• skill-developer → スキルのガバナンス

---

12. オペレーターの検証チェックリスト

バックエンド作業を完了する前に：

• 根拠を示してリスクを議論済み。数値スコアだけで承認していない
• レイヤードアーキテクチャを遵守している
• 入力を検証済み
• Sentry でエラーを捕捉している
• unifiedConfig を使用している
• テストを作成済み
• アンチパターンが存在しない

---

13. スキルのステータス

ステータス： 例示的なパターンです。対象環境でのコンパイル、テスト、セキュリティレビューが必要です
想定用途： 実際のトラフィックと実際のリスクを伴う、長期運用の Node.js マイクロサービス

使用するタイミング

このスキルは、概要に記載されたワークフローまたはアクションを実行する場合に適用できます。

制限事項

• このスキルは、タスクが上記の範囲に明確に合致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。