@k2works/claude-code-booster 3.6.1 → 3.7.0

package/lib/assets/docs/article/practical-database-design/part5/chapter38.md

@@ -1,1698 +1,1698 @@
-# 第38章：API 設計とサービス連携
-
-本章では、基幹業務システムにおける API 設計の原則と、サービス間連携のパターンについて解説します。RESTful API の設計、サービス間通信の方式、API ゲートウェイの活用、そしてインテグレーションテストの実践方法を学びます。
-
----
-
-## 38.1 API 設計の原則
-
-### RESTful API の設計
-
-REST（Representational State Transfer）は、Web API 設計の標準的なアーキテクチャスタイルです。
-
-```plantuml
-@startuml
-title RESTful API の基本原則
-
-rectangle "REST の制約" as constraints {
-    rectangle "クライアント-サーバー" as cs {
-        note right
-          関心の分離
-          独立した進化
-        end note
-    }
-
-    rectangle "ステートレス" as stateless {
-        note right
-          各リクエストは独立
-          セッション状態を保持しない
-        end note
-    }
-
-    rectangle "キャッシュ可能" as cacheable {
-        note right
-          レスポンスにキャッシュ可否を明示
-          パフォーマンス向上
-        end note
-    }
-
-    rectangle "統一インターフェース" as uniform {
-        note right
-          リソース識別（URI）
-          表現によるリソース操作
-          自己記述メッセージ
-          HATEOAS
-        end note
-    }
-
-    rectangle "階層化システム" as layered {
-        note right
-          中間サーバーの追加が可能
-          ロードバランサー、キャッシュ等
-        end note
-    }
-}
-
-@enduml
-```
-
-#### HTTP メソッドとリソース操作
-
-| HTTP メソッド | 操作 | 冪等性 | 安全性 | 使用例 |
-|-------------|-----|-------|-------|-------|
-| GET | 取得 | Yes | Yes | リソースの参照 |
-| POST | 作成 | No | No | 新規リソース作成 |
-| PUT | 置換 | Yes | No | リソース全体の更新 |
-| PATCH | 部分更新 | No | No | リソースの一部更新 |
-| DELETE | 削除 | Yes | No | リソースの削除 |
-
-### リソース指向設計
-
-API はリソース（名詞）を中心に設計し、操作は HTTP メソッドで表現します。
-
-```plantuml
-@startuml
-title リソース指向 API 設計
-
-package "販売管理 API" as sales_api {
-    rectangle "/orders" as orders {
-        rectangle "GET /orders" as get_orders
-        rectangle "POST /orders" as post_order
-        rectangle "GET /orders/{id}" as get_order
-        rectangle "PUT /orders/{id}" as put_order
-        rectangle "DELETE /orders/{id}" as delete_order
-    }
-
-    rectangle "/orders/{id}/lines" as order_lines {
-        rectangle "GET /orders/{id}/lines" as get_lines
-        rectangle "POST /orders/{id}/lines" as post_line
-    }
-
-    rectangle "/customers" as customers {
-        rectangle "GET /customers" as get_customers
-        rectangle "POST /customers" as post_customer
-        rectangle "GET /customers/{id}" as get_customer
-    }
-
-    rectangle "/customers/{id}/orders" as customer_orders {
-        rectangle "GET /customers/{id}/orders" as get_customer_orders
-    }
-}
-
-note bottom of sales_api
-  【設計原則】
-  ・リソースは名詞（複数形）
-  ・操作はHTTPメソッドで表現
-  ・階層構造で関連を表現
-  ・クエリパラメータでフィルタリング
-end note
-
-@enduml
-```
-
-#### 基幹業務システムの API エンドポイント設計
-
-```plantuml
-@startuml
-title 基幹業務システム API エンドポイント
-
-package "販売管理 API" as sales {
-    rectangle "/api/v1/sales" as sales_base {
-        rectangle "受注: /orders"
-        rectangle "出荷: /shipments"
-        rectangle "売上: /sales"
-        rectangle "請求: /invoices"
-        rectangle "入金: /payments"
-    }
-    rectangle "/api/v1/sales/masters" as sales_masters {
-        rectangle "顧客: /customers"
-        rectangle "商品: /products"
-    }
-}
-
-package "財務会計 API" as accounting {
-    rectangle "/api/v1/accounting" as acc_base {
-        rectangle "仕訳: /journals"
-        rectangle "残高: /balances"
-        rectangle "試算表: /trial-balances"
-    }
-    rectangle "/api/v1/accounting/masters" as acc_masters {
-        rectangle "勘定科目: /accounts"
-        rectangle "補助科目: /sub-accounts"
-    }
-}
-
-package "生産管理 API" as production {
-    rectangle "/api/v1/production" as prod_base {
-        rectangle "製造指示: /work-orders"
-        rectangle "発注: /purchase-orders"
-        rectangle "在庫: /inventory"
-    }
-    rectangle "/api/v1/production/masters" as prod_masters {
-        rectangle "品目: /items"
-        rectangle "BOM: /bom"
-        rectangle "工程: /processes"
-    }
-}
-
-@enduml
-```
-
-<details>
-<summary>OpenAPI 定義例</summary>
-
-```yaml
-openapi: 3.0.3
-info:
-  title: 販売管理 API
-  version: 1.0.0
-  description: 基幹業務システム - 販売管理 API
-
-servers:
-  - url: https://api.example.com/api/v1/sales
-    description: Production server
-
-paths:
-  /orders:
-    get:
-      summary: 受注一覧取得
-      operationId: getOrders
-      parameters:
-        - name: customerId
-          in: query
-          schema:
-            type: string
-        - name: status
-          in: query
-          schema:
-            type: string
-            enum: [DRAFT, CONFIRMED, SHIPPED, COMPLETED]
-        - name: fromDate
-          in: query
-          schema:
-            type: string
-            format: date
-        - name: toDate
-          in: query
-          schema:
-            type: string
-            format: date
-        - name: page
-          in: query
-          schema:
-            type: integer
-            default: 0
-        - name: size
-          in: query
-          schema:
-            type: integer
-            default: 20
-      responses:
-        '200':
-          description: 成功
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/OrderListResponse'
-
-    post:
-      summary: 受注登録
-      operationId: createOrder
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/CreateOrderRequest'
-      responses:
-        '201':
-          description: 作成成功
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/OrderResponse'
-        '400':
-          description: バリデーションエラー
-          content:
-            application/problem+json:
-              schema:
-                $ref: '#/components/schemas/ProblemDetail'
-
-  /orders/{orderId}:
-    get:
-      summary: 受注詳細取得
-      operationId: getOrder
-      parameters:
-        - name: orderId
-          in: path
-          required: true
-          schema:
-            type: string
-      responses:
-        '200':
-          description: 成功
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/OrderResponse'
-        '404':
-          description: 受注が見つからない
-
-components:
-  schemas:
-    OrderResponse:
-      type: object
-      properties:
-        orderId:
-          type: string
-        customerId:
-          type: string
-        customerName:
-          type: string
-        orderDate:
-          type: string
-          format: date
-        status:
-          type: string
-          enum: [DRAFT, CONFIRMED, SHIPPED, COMPLETED]
-        totalAmount:
-          type: number
-        taxAmount:
-          type: number
-        lines:
-          type: array
-          items:
-            $ref: '#/components/schemas/OrderLineResponse'
-        _links:
-          $ref: '#/components/schemas/Links'
-
-    CreateOrderRequest:
-      type: object
-      required:
-        - customerId
-        - orderDate
-        - lines
-      properties:
-        customerId:
-          type: string
-        orderDate:
-          type: string
-          format: date
-        requestedDeliveryDate:
-          type: string
-          format: date
-        lines:
-          type: array
-          items:
-            $ref: '#/components/schemas/CreateOrderLineRequest'
-          minItems: 1
-
-    ProblemDetail:
-      type: object
-      properties:
-        type:
-          type: string
-        title:
-          type: string
-        status:
-          type: integer
-        detail:
-          type: string
-        instance:
-          type: string
-```
-
-</details>
-
-### バージョニング戦略
-
-API の互換性を維持しながら進化させるためのバージョニング戦略を検討します。
-
-```plantuml
-@startuml
-title API バージョニング戦略の比較
-
-rectangle "URI パスバージョニング" as uri {
-    note right
-      /api/v1/orders
-      /api/v2/orders
-
-      【メリット】
-      ・明確で分かりやすい
-      ・キャッシュしやすい
-
-      【デメリット】
-      ・URIの変更が必要
-    end note
-}
-
-rectangle "クエリパラメータ" as query {
-    note right
-      /api/orders?version=1
-      /api/orders?version=2
-
-      【メリット】
-      ・URIが変わらない
-
-      【デメリット】
-      ・見落としやすい
-    end note
-}
-
-rectangle "カスタムヘッダー" as header {
-    note right
-      X-API-Version: 1
-      X-API-Version: 2
-
-      【メリット】
-      ・URIがクリーン
-
-      【デメリット】
-      ・テストしにくい
-    end note
-}
-
-rectangle "Accept ヘッダー" as accept {
-    note right
-      Accept: application/vnd.company.v1+json
-      Accept: application/vnd.company.v2+json
-
-      【メリット】
-      ・HTTP標準に準拠
-
-      【デメリット】
-      ・複雑
-    end note
-}
-
-@enduml
-```
-
-#### 推奨：URI パスバージョニング
-
-```plantuml
-@startuml
-title URI パスバージョニングの運用
-
-rectangle "v1（現行）" as v1 {
-    rectangle "/api/v1/orders" as v1_orders
-    rectangle "/api/v1/customers" as v1_customers
-}
-
-rectangle "v2（新版）" as v2 {
-    rectangle "/api/v2/orders" as v2_orders
-    rectangle "/api/v2/customers" as v2_customers
-}
-
-note bottom of v1
-  【v1 → v2 移行】
-  1. v2を新規リリース
-  2. 並行運用期間
-  3. v1を非推奨化（Deprecation）
-  4. v1を廃止（Sunset）
-
-  【Deprecation ヘッダー】
-  Deprecation: true
-  Sunset: Sat, 01 Jan 2025 00:00:00 GMT
-end note
-
-@enduml
-```
-
----
-
-## 38.2 サービス間通信
-
-### 同期通信（REST / gRPC）
-
-```plantuml
-@startuml
-title 同期通信パターンの比較
-
-rectangle "REST over HTTP" as rest {
-    rectangle "販売サービス" as sales_rest
-    rectangle "在庫サービス" as inv_rest
-
-    sales_rest --> inv_rest : HTTP/JSON
-}
-
-rectangle "gRPC" as grpc {
-    rectangle "販売サービス" as sales_grpc
-    rectangle "在庫サービス" as inv_grpc
-
-    sales_grpc --> inv_grpc : HTTP/2 + Protocol Buffers
-}
-
-note bottom of rest
-  【REST】
-  ・テキストベース（JSON）
-  ・ブラウザから直接呼び出し可能
-  ・広く普及、ツール豊富
-
-  【適用場面】
-  ・外部公開API
-  ・フロントエンド連携
-end note
-
-note bottom of grpc
-  【gRPC】
-  ・バイナリプロトコル
-  ・高速、低レイテンシ
-  ・スキーマ定義必須
-
-  【適用場面】
-  ・マイクロサービス間
-  ・高性能要件
-end note
-
-@enduml
-```
-
-<details>
-<summary>gRPC 定義例</summary>
-
-```protobuf
-syntax = "proto3";
-
-package sales.v1;
-
-option java_package = "com.example.sales.grpc";
-option java_multiple_files = true;
-
-// 在庫サービス
-service InventoryService {
-  // 在庫照会
-  rpc GetStock(GetStockRequest) returns (StockResponse);
-
-  // 在庫引当
-  rpc AllocateStock(AllocateStockRequest) returns (AllocateStockResponse);
-
-  // 引当解除
-  rpc ReleaseStock(ReleaseStockRequest) returns (ReleaseStockResponse);
-}
-
-message GetStockRequest {
-  string product_id = 1;
-  string warehouse_id = 2;
-}
-
-message StockResponse {
-  string product_id = 1;
-  string warehouse_id = 2;
-  int32 quantity = 3;
-  int32 allocated_quantity = 4;
-  int32 available_quantity = 5;
-}
-
-message AllocateStockRequest {
-  string product_id = 1;
-  string warehouse_id = 2;
-  int32 quantity = 3;
-  string order_id = 4;
-}
-
-message AllocateStockResponse {
-  bool success = 1;
-  string allocation_id = 2;
-  string error_message = 3;
-}
-```
-
-</details>
-
-### 非同期通信（メッセージキュー）
-
-```plantuml
-@startuml
-title 非同期通信パターン
-
-rectangle "販売サービス" as sales
-
-rectangle "メッセージブローカー" as broker {
-    queue "受注キュー" as order_queue
-    collections "売上トピック" as sales_topic
-}
-
-rectangle "在庫サービス" as inventory
-rectangle "会計サービス" as accounting
-rectangle "通知サービス" as notification
-
-sales --> order_queue : 受注メッセージ
-order_queue --> inventory : 在庫引当
-
-sales --> sales_topic : 売上イベント
-sales_topic --> accounting : 仕訳生成
-sales_topic --> notification : 通知送信
-sales_topic --> inventory : 在庫更新
-
-note bottom of broker
-  【Point-to-Point】
-  ・1対1の通信
-  ・キューで実現
-  ・負荷分散可能
-
-  【Publish-Subscribe】
-  ・1対多の通信
-  ・トピックで実現
-  ・イベント配信
-end note
-
-@enduml
-```
-
-<details>
-<summary>Java 実装例（Spring AMQP）</summary>
-
-```java
-// メッセージ送信
-@Service
-public class OrderMessagePublisher {
-    private final RabbitTemplate rabbitTemplate;
-
-    public void publishOrderCreated(OrderCreatedEvent event) {
-        rabbitTemplate.convertAndSend(
-            "sales.exchange",
-            "order.created",
-            event
-        );
-    }
-
-    public void publishSalesCompleted(SalesCompletedEvent event) {
-        rabbitTemplate.convertAndSend(
-            "sales.topic.exchange",
-            "sales.completed",
-            event
-        );
-    }
-}
-
-// メッセージ受信
-@Component
-public class OrderMessageListener {
-
-    @RabbitListener(queues = "inventory.order.queue")
-    public void handleOrderCreated(OrderCreatedEvent event) {
-        // 在庫引当処理
-        log.info("Received order: {}", event.orderId());
-        inventoryService.allocate(event);
-    }
-}
-
-// 設定
-@Configuration
-public class RabbitMQConfig {
-
-    @Bean
-    public TopicExchange salesTopicExchange() {
-        return new TopicExchange("sales.topic.exchange");
-    }
-
-    @Bean
-    public Queue accountingQueue() {
-        return new Queue("accounting.sales.queue", true);
-    }
-
-    @Bean
-    public Binding accountingBinding(Queue accountingQueue,
-                                      TopicExchange salesTopicExchange) {
-        return BindingBuilder.bind(accountingQueue)
-            .to(salesTopicExchange)
-            .with("sales.*");
-    }
-}
-```
-
-</details>
-
-### サーキットブレーカーパターン
-
-サービス間通信の障害を検知し、障害の連鎖を防ぐパターンです。
-
-```plantuml
-@startuml
-title サーキットブレーカーの状態遷移
-
-[*] --> Closed : 初期状態
-
-Closed --> Open : 失敗が閾値を超過
-Closed --> Closed : 成功
-
-Open --> HalfOpen : タイムアウト後
-Open --> Open : リクエスト拒否
-
-HalfOpen --> Closed : 試行成功
-HalfOpen --> Open : 試行失敗
-
-note right of Closed
-  【Closed】
-  通常稼働
-  リクエストを通す
-end note
-
-note right of Open
-  【Open】
-  障害検知
-  即座にエラー返却
-  （Fail Fast）
-end note
-
-note right of HalfOpen
-  【Half-Open】
-  復旧確認中
-  限定的に試行
-end note
-
-@enduml
-```
-
-```plantuml
-@startuml
-title サーキットブレーカーの動作フロー
-
-|クライアント|
-start
-:サービス呼び出し;
-
-|サーキットブレーカー|
-if (回路状態?) then (Open)
-    :即座にフォールバック;
-    |クライアント|
-    :フォールバック結果;
-    stop
-else (Closed/HalfOpen)
-endif
-
-:下流サービス呼び出し;
-
-|下流サービス|
-if (処理成功?) then (yes)
-    :正常レスポンス;
-    |サーキットブレーカー|
-    :成功をカウント;
-    :Closedを維持/遷移;
-else (no)
-    :エラー/タイムアウト;
-    |サーキットブレーカー|
-    :失敗をカウント;
-
-    if (失敗数 >= 閾値?) then (yes)
-        :Openに遷移;
-    endif
-endif
-
-|クライアント|
-:結果を返却;
-
-stop
-
-@enduml
-```
-
-<details>
-<summary>Java 実装例（Resilience4j）</summary>
-
-```java
-// 設定
-@Configuration
-public class CircuitBreakerConfig {
-
-    @Bean
-    public CircuitBreakerRegistry circuitBreakerRegistry() {
-        CircuitBreakerConfig config = CircuitBreakerConfig.custom()
-            .failureRateThreshold(50)  // 失敗率50%でOpen
-            .waitDurationInOpenState(Duration.ofSeconds(30))
-            .permittedNumberOfCallsInHalfOpenState(3)
-            .slidingWindowType(SlidingWindowType.COUNT_BASED)
-            .slidingWindowSize(10)
-            .build();
-
-        return CircuitBreakerRegistry.of(config);
-    }
-}
-
-// サービス
-@Service
-public class InventoryServiceClient {
-    private final RestTemplate restTemplate;
-    private final CircuitBreaker circuitBreaker;
-
-    public InventoryServiceClient(RestTemplate restTemplate,
-                                   CircuitBreakerRegistry registry) {
-        this.restTemplate = restTemplate;
-        this.circuitBreaker = registry.circuitBreaker("inventoryService");
-    }
-
-    public StockResponse getStock(String productId) {
-        Supplier<StockResponse> supplier = CircuitBreaker
-            .decorateSupplier(circuitBreaker, () -> {
-                return restTemplate.getForObject(
-                    "/api/v1/inventory/{productId}",
-                    StockResponse.class,
-                    productId
-                );
-            });
-
-        return Try.ofSupplier(supplier)
-            .recover(CallNotPermittedException.class,
-                e -> getFallbackStock(productId))
-            .recover(Exception.class,
-                e -> getFallbackStock(productId))
-            .get();
-    }
-
-    private StockResponse getFallbackStock(String productId) {
-        // フォールバック: キャッシュから取得または推定値
-        return new StockResponse(productId, 0, 0, 0, "UNKNOWN");
-    }
-}
-
-// アノテーションベース
-@Service
-public class AccountingServiceClient {
-
-    @CircuitBreaker(name = "accountingService", fallbackMethod = "fallback")
-    @Retry(name = "accountingService")
-    @TimeLimiter(name = "accountingService")
-    public CompletableFuture<JournalResponse> createJournal(
-            CreateJournalRequest request) {
-        return CompletableFuture.supplyAsync(() -> {
-            return restTemplate.postForObject(
-                "/api/v1/accounting/journals",
-                request,
-                JournalResponse.class
-            );
-        });
-    }
-
-    public CompletableFuture<JournalResponse> fallback(
-            CreateJournalRequest request, Throwable t) {
-        log.warn("Fallback for createJournal: {}", t.getMessage());
-        // 仕訳をキューに保存して後で再試行
-        pendingJournalQueue.add(request);
-        return CompletableFuture.completedFuture(
-            JournalResponse.pending(request.getCorrelationId())
-        );
-    }
-}
-```
-
-</details>
-
----
-
-## 38.3 API ゲートウェイ
-
-API ゲートウェイは、クライアントと複数のバックエンドサービスの間に位置し、横断的な関心事を一元的に処理します。
-
-```plantuml
-@startuml
-title API ゲートウェイアーキテクチャ
-
-rectangle "クライアント" as clients {
-    rectangle "Webアプリ" as web
-    rectangle "モバイルアプリ" as mobile
-    rectangle "外部システム" as external
-}
-
-rectangle "API Gateway" as gateway {
-    rectangle "認証・認可" as auth
-    rectangle "レート制限" as rate
-    rectangle "ルーティング" as routing
-    rectangle "ログ・監視" as logging
-    rectangle "変換・集約" as transform
-}
-
-rectangle "バックエンドサービス" as backend {
-    rectangle "販売API" as sales
-    rectangle "会計API" as accounting
-    rectangle "生産API" as production
-}
-
-web --> gateway
-mobile --> gateway
-external --> gateway
-
-gateway --> sales
-gateway --> accounting
-gateway --> production
-
-note bottom of gateway
-  【API Gatewayの責務】
-  ・認証・認可の一元化
-  ・レート制限
-  ・リクエストルーティング
-  ・ログ集約
-  ・レスポンス変換
-  ・API集約
-end note
-
-@enduml
-```
-
-### 認証・認可の一元化
-
-```plantuml
-@startuml
-title JWT 認証フロー
-
-|クライアント|
-start
-:認証リクエスト;
-note right
-  POST /auth/login
-  {username, password}
-end note
-
-|認証サービス|
-:認証情報検証;
-:JWTトークン発行;
-note right
-  Header: {alg, typ}
-  Payload: {sub, roles, exp}
-  Signature
-end note
-
-|クライアント|
-:JWTトークン保存;
-:API呼び出し;
-note right
-  Authorization: Bearer {token}
-end note
-
-|API Gateway|
-:JWTトークン検証;
-if (有効?) then (yes)
-    :クレーム抽出;
-    :認可チェック;
-    if (権限あり?) then (yes)
-        |バックエンドサービス|
-        :リクエスト処理;
-        :レスポンス返却;
-    else (no)
-        :403 Forbidden;
-    endif
-else (no)
-    :401 Unauthorized;
-endif
-
-|クライアント|
-:結果受信;
-
-stop
-
-@enduml
-```
-
-<details>
-<summary>Java 実装例（Spring Security + JWT）</summary>
-
-```java
-// JWT フィルター
-@Component
-public class JwtAuthenticationFilter extends OncePerRequestFilter {
-    private final JwtTokenProvider tokenProvider;
-
-    @Override
-    protected void doFilterInternal(HttpServletRequest request,
-                                     HttpServletResponse response,
-                                     FilterChain filterChain)
-            throws ServletException, IOException {
-
-        String token = extractToken(request);
-
-        if (token != null && tokenProvider.validateToken(token)) {
-            Authentication auth = tokenProvider.getAuthentication(token);
-            SecurityContextHolder.getContext().setAuthentication(auth);
-        }
-
-        filterChain.doFilter(request, response);
-    }
-
-    private String extractToken(HttpServletRequest request) {
-        String bearerToken = request.getHeader("Authorization");
-        if (bearerToken != null && bearerToken.startsWith("Bearer ")) {
-            return bearerToken.substring(7);
-        }
-        return null;
-    }
-}
-
-// JWT プロバイダー
-@Component
-public class JwtTokenProvider {
-    @Value("${jwt.secret}")
-    private String jwtSecret;
-
-    @Value("${jwt.expiration}")
-    private long jwtExpiration;
-
-    public String generateToken(Authentication authentication) {
-        UserDetails userDetails = (UserDetails) authentication.getPrincipal();
-
-        return Jwts.builder()
-            .setSubject(userDetails.getUsername())
-            .claim("roles", userDetails.getAuthorities().stream()
-                .map(GrantedAuthority::getAuthority)
-                .collect(Collectors.toList()))
-            .setIssuedAt(new Date())
-            .setExpiration(new Date(System.currentTimeMillis() + jwtExpiration))
-            .signWith(SignatureAlgorithm.HS512, jwtSecret)
-            .compact();
-    }
-
-    public boolean validateToken(String token) {
-        try {
-            Jwts.parser().setSigningKey(jwtSecret).parseClaimsJws(token);
-            return true;
-        } catch (JwtException | IllegalArgumentException e) {
-            return false;
-        }
-    }
-
-    public Authentication getAuthentication(String token) {
-        Claims claims = Jwts.parser()
-            .setSigningKey(jwtSecret)
-            .parseClaimsJws(token)
-            .getBody();
-
-        List<String> roles = claims.get("roles", List.class);
-        List<GrantedAuthority> authorities = roles.stream()
-            .map(SimpleGrantedAuthority::new)
-            .collect(Collectors.toList());
-
-        User principal = new User(claims.getSubject(), "", authorities);
-        return new UsernamePasswordAuthenticationToken(
-            principal, token, authorities
-        );
-    }
-}
-```
-
-</details>
-
-### レート制限とスロットリング
-
-```plantuml
-@startuml
-title レート制限アルゴリズム
-
-rectangle "Token Bucket" as token_bucket {
-    note right
-      ・バケットにトークンを蓄積
-      ・リクエスト時にトークン消費
-      ・バースト対応可能
-
-      設定例:
-      rate: 100/分
-      burst: 20
-    end note
-}
-
-rectangle "Sliding Window" as sliding_window {
-    note right
-      ・時間枠内のリクエスト数をカウント
-      ・枠をスライドして計算
-      ・より正確な制限
-
-      設定例:
-      window: 1分
-      limit: 100
-    end note
-}
-
-rectangle "Fixed Window" as fixed_window {
-    note right
-      ・固定時間枠でカウント
-      ・シンプルな実装
-      ・境界でバーストの可能性
-
-      設定例:
-      window: 1分
-      limit: 100
-    end note
-}
-
-@enduml
-```
-
-<details>
-<summary>Spring Cloud Gateway 設定例</summary>
-
-```yaml
-# application.yml
-spring:
-  cloud:
-    gateway:
-      routes:
-        - id: sales-service
-          uri: lb://sales-service
-          predicates:
-            - Path=/api/v1/sales/**
-          filters:
-            - name: RequestRateLimiter
-              args:
-                redis-rate-limiter.replenishRate: 100
-                redis-rate-limiter.burstCapacity: 200
-                key-resolver: "#{@userKeyResolver}"
-            - name: CircuitBreaker
-              args:
-                name: salesCircuitBreaker
-                fallbackUri: forward:/fallback/sales
-
-        - id: accounting-service
-          uri: lb://accounting-service
-          predicates:
-            - Path=/api/v1/accounting/**
-          filters:
-            - name: RequestRateLimiter
-              args:
-                redis-rate-limiter.replenishRate: 50
-                redis-rate-limiter.burstCapacity: 100
-
-      default-filters:
-        - name: Retry
-          args:
-            retries: 3
-            statuses: BAD_GATEWAY,SERVICE_UNAVAILABLE
-            methods: GET
-            backoff:
-              firstBackoff: 100ms
-              maxBackoff: 500ms
-              factor: 2
-```
-
-```java
-// Key Resolver（ユーザー単位のレート制限）
-@Configuration
-public class RateLimiterConfig {
-
-    @Bean
-    public KeyResolver userKeyResolver() {
-        return exchange -> {
-            String userId = exchange.getRequest()
-                .getHeaders()
-                .getFirst("X-User-Id");
-            return Mono.just(userId != null ? userId : "anonymous");
-        };
-    }
-
-    @Bean
-    public KeyResolver apiKeyResolver() {
-        return exchange -> {
-            String apiKey = exchange.getRequest()
-                .getHeaders()
-                .getFirst("X-API-Key");
-            return Mono.just(apiKey != null ? apiKey : "default");
-        };
-    }
-}
-```
-
-</details>
-
-### ログ集約とモニタリング
-
-```plantuml
-@startuml
-title 分散トレーシングとログ集約
-
-rectangle "クライアント" as client
-
-rectangle "API Gateway" as gateway {
-    rectangle "トレースID生成" as trace_gen
-}
-
-rectangle "サービス群" as services {
-    rectangle "販売サービス" as sales
-    rectangle "在庫サービス" as inventory
-    rectangle "会計サービス" as accounting
-}
-
-rectangle "観測基盤" as observability {
-    database "ログ集約\n(ELK/Loki)" as logs
-    database "メトリクス\n(Prometheus)" as metrics
-    database "トレース\n(Jaeger/Zipkin)" as traces
-}
-
-rectangle "ダッシュボード" as dashboard {
-    rectangle "Grafana" as grafana
-    rectangle "Kibana" as kibana
-}
-
-client --> gateway : リクエスト
-gateway --> sales : traceId
-sales --> inventory : traceId
-sales --> accounting : traceId
-
-gateway --> logs
-sales --> logs
-inventory --> logs
-accounting --> logs
-
-gateway --> metrics
-sales --> metrics
-inventory --> metrics
-accounting --> metrics
-
-gateway --> traces
-sales --> traces
-inventory --> traces
-accounting --> traces
-
-logs --> kibana
-metrics --> grafana
-traces --> grafana
-
-@enduml
-```
-
-<details>
-<summary>Java 実装例（Micrometer + OpenTelemetry）</summary>
-
-```java
-// トレーシング設定
-@Configuration
-public class TracingConfig {
-
-    @Bean
-    public Tracer tracer() {
-        return GlobalOpenTelemetry.getTracer("sales-service");
-    }
-}
-
-// カスタムメトリクス
-@Component
-public class OrderMetrics {
-    private final MeterRegistry meterRegistry;
-    private final Counter orderCreatedCounter;
-    private final Timer orderProcessingTimer;
-
-    public OrderMetrics(MeterRegistry meterRegistry) {
-        this.meterRegistry = meterRegistry;
-
-        this.orderCreatedCounter = Counter.builder("orders.created")
-            .description("Number of orders created")
-            .tag("service", "sales")
-            .register(meterRegistry);
-
-        this.orderProcessingTimer = Timer.builder("orders.processing.time")
-            .description("Order processing time")
-            .tag("service", "sales")
-            .register(meterRegistry);
-    }
-
-    public void recordOrderCreated(String status) {
-        orderCreatedCounter.increment();
-        meterRegistry.counter("orders.created.by.status",
-            "status", status).increment();
-    }
-
-    public void recordProcessingTime(long durationMs) {
-        orderProcessingTimer.record(Duration.ofMillis(durationMs));
-    }
-}
-
-// 構造化ログ
-@Slf4j
-@Service
-public class OrderService {
-
-    public Order createOrder(CreateOrderRequest request) {
-        MDC.put("orderId", request.getOrderId());
-        MDC.put("customerId", request.getCustomerId());
-
-        try {
-            log.info("Creating order", kv("action", "create_order_start"));
-
-            Order order = processOrder(request);
-
-            log.info("Order created successfully",
-                kv("action", "create_order_complete"),
-                kv("totalAmount", order.getTotalAmount()));
-
-            return order;
-        } catch (Exception e) {
-            log.error("Failed to create order",
-                kv("action", "create_order_failed"),
-                kv("error", e.getMessage()), e);
-            throw e;
-        } finally {
-            MDC.clear();
-        }
-    }
-}
-```
-
-</details>
-
----
-
-## 38.4 API インテグレーションテスト
-
-### テストコンテナによる統合テスト環境
-
-```plantuml
-@startuml
-title テストコンテナアーキテクチャ
-
-rectangle "テスト実行環境" as test_env {
-    rectangle "JUnit 5" as junit
-    rectangle "テストクラス" as test_class
-}
-
-rectangle "Testcontainers" as testcontainers {
-    rectangle "PostgreSQL\nコンテナ" as postgres
-    rectangle "RabbitMQ\nコンテナ" as rabbitmq
-    rectangle "Redis\nコンテナ" as redis
-}
-
-rectangle "アプリケーション" as app {
-    rectangle "Spring Boot\nアプリケーション" as spring
-}
-
-test_class --> spring : HTTP リクエスト
-spring --> postgres : データアクセス
-spring --> rabbitmq : メッセージング
-spring --> redis : キャッシュ
-
-junit --> testcontainers : コンテナ起動
-testcontainers --> postgres
-testcontainers --> rabbitmq
-testcontainers --> redis
-
-note bottom of testcontainers
-  【Testcontainersの利点】
-  ・本番同等の環境でテスト
-  ・テスト間の分離
-  ・CI/CDでの再現性
-  ・自動クリーンアップ
-end note
-
-@enduml
-```
-
-<details>
-<summary>Java 実装例</summary>
-
-```java
-// テストコンテナ設定
-@Testcontainers
-@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
-@ActiveProfiles("test")
-public abstract class IntegrationTestBase {
-
-    @Container
-    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15")
-        .withDatabaseName("testdb")
-        .withUsername("test")
-        .withPassword("test");
-
-    @Container
-    static RabbitMQContainer rabbitmq = new RabbitMQContainer("rabbitmq:3.12-management");
-
-    @DynamicPropertySource
-    static void configureProperties(DynamicPropertyRegistry registry) {
-        registry.add("spring.datasource.url", postgres::getJdbcUrl);
-        registry.add("spring.datasource.username", postgres::getUsername);
-        registry.add("spring.datasource.password", postgres::getPassword);
-        registry.add("spring.rabbitmq.host", rabbitmq::getHost);
-        registry.add("spring.rabbitmq.port", rabbitmq::getAmqpPort);
-    }
-
-    @Autowired
-    protected TestRestTemplate restTemplate;
-
-    @Autowired
-    protected JdbcTemplate jdbcTemplate;
-
-    @BeforeEach
-    void setUp() {
-        // テストデータのクリーンアップ
-        cleanupTestData();
-    }
-
-    protected void cleanupTestData() {
-        jdbcTemplate.execute("TRUNCATE TABLE 受注明細 CASCADE");
-        jdbcTemplate.execute("TRUNCATE TABLE 受注 CASCADE");
-    }
-}
-```
-
-</details>
-
-### REST API エンドポイントのテスト
-
-```plantuml
-@startuml
-title API テストの構造
-
-' ノード間の間隔を調整
-skinparam nodesep 50
-skinparam ranksep 50
-
-rectangle "== Given（前提条件）\n\n・テストデータ準備\n・認証トークン取得\n・モックの設定" as given
-
-rectangle "== When（操作）\n\n・APIエンドポイント呼び出し\n・リクエストボディ設定\n・ヘッダー設定" as when
-
-rectangle "== Then（検証）\n\n・ステータスコード確認\n・レスポンスボディ検証\n・データベース状態確認\n・イベント発行確認" as then
-
-given --> when
-when --> then
-
-@enduml
-```
-
-<details>
-<summary>Java 実装例</summary>
-
-```java
-// 受注API統合テスト
-class OrderApiIntegrationTest extends IntegrationTestBase {
-
-    @Autowired
-    private CustomerRepository customerRepository;
-
-    @Autowired
-    private ProductRepository productRepository;
-
-    private String authToken;
-    private Customer testCustomer;
-    private Product testProduct;
-
-    @BeforeEach
-    void setUpTestData() {
-        // 認証トークン取得
-        authToken = getAuthToken("test-user", "password");
-
-        // テストデータ準備
-        testCustomer = customerRepository.save(
-            new Customer("CUS-001", "テスト顧客", "test@example.com")
-        );
-        testProduct = productRepository.save(
-            new Product("PRD-001", "テスト商品", new BigDecimal("1000"))
-        );
-    }
-
-    @Test
-    @DisplayName("受注登録: 正常系")
-    void createOrder_Success() {
-        // Given
-        CreateOrderRequest request = CreateOrderRequest.builder()
-            .customerId(testCustomer.getCustomerId())
-            .orderDate(LocalDate.now())
-            .lines(List.of(
-                OrderLineRequest.builder()
-                    .productId(testProduct.getProductId())
-                    .quantity(10)
-                    .build()
-            ))
-            .build();
-
-        // When
-        ResponseEntity<OrderResponse> response = restTemplate.exchange(
-            "/api/v1/sales/orders",
-            HttpMethod.POST,
-            new HttpEntity<>(request, createAuthHeaders()),
-            OrderResponse.class
-        );
-
-        // Then
-        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED);
-        assertThat(response.getBody()).isNotNull();
-        assertThat(response.getBody().getOrderId()).isNotBlank();
-        assertThat(response.getBody().getStatus()).isEqualTo("DRAFT");
-        assertThat(response.getBody().getTotalAmount())
-            .isEqualByComparingTo(new BigDecimal("10000"));
-
-        // データベース状態確認
-        Order savedOrder = orderRepository.findById(
-            response.getBody().getOrderId()
-        ).orElseThrow();
-        assertThat(savedOrder.getCustomerId()).isEqualTo(testCustomer.getCustomerId());
-        assertThat(savedOrder.getLines()).hasSize(1);
-    }
-
-    @Test
-    @DisplayName("受注登録: バリデーションエラー")
-    void createOrder_ValidationError() {
-        // Given - 明細なしのリクエスト
-        CreateOrderRequest request = CreateOrderRequest.builder()
-            .customerId(testCustomer.getCustomerId())
-            .orderDate(LocalDate.now())
-            .lines(List.of()) // 空の明細
-            .build();
-
-        // When
-        ResponseEntity<ProblemDetail> response = restTemplate.exchange(
-            "/api/v1/sales/orders",
-            HttpMethod.POST,
-            new HttpEntity<>(request, createAuthHeaders()),
-            ProblemDetail.class
-        );
-
-        // Then
-        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.BAD_REQUEST);
-        assertThat(response.getBody().getTitle()).isEqualTo("Validation Error");
-    }
-
-    @Test
-    @DisplayName("受注一覧取得: ページング")
-    void getOrders_Paging() {
-        // Given - 複数の受注を作成
-        for (int i = 0; i < 25; i++) {
-            createTestOrder("ORD-" + String.format("%03d", i));
-        }
-
-        // When
-        ResponseEntity<PagedResponse<OrderSummary>> response = restTemplate.exchange(
-            "/api/v1/sales/orders?page=0&size=10",
-            HttpMethod.GET,
-            new HttpEntity<>(createAuthHeaders()),
-            new ParameterizedTypeReference<>() {}
-        );
-
-        // Then
-        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
-        assertThat(response.getBody().getContent()).hasSize(10);
-        assertThat(response.getBody().getTotalElements()).isEqualTo(25);
-        assertThat(response.getBody().getTotalPages()).isEqualTo(3);
-    }
-
-    private HttpHeaders createAuthHeaders() {
-        HttpHeaders headers = new HttpHeaders();
-        headers.setBearerAuth(authToken);
-        headers.setContentType(MediaType.APPLICATION_JSON);
-        return headers;
-    }
-}
-```
-
-</details>
-
-### サービス間連携テスト
-
-```plantuml
-@startuml
-title サービス間連携テストのアプローチ
-
-' ボックスの定義
-rectangle "Contract Testing" as contract
-note right of contract
-  ・Pact / Spring Cloud Contract
-  ・プロバイダーとコンシューマーの契約
-  ・独立したテスト実行
-end note
-
-rectangle "Component Testing" as component
-note right of component
-  ・WireMockで外部サービスをモック
-  ・単一サービスの統合テスト
-  ・高速なフィードバック
-end note
-
-rectangle "End-to-End Testing" as e2e
-note right of e2e
-  ・全サービスを起動
-  ・Docker Composeで環境構築
-  ・本番同等のシナリオテスト
-end note
-
-' 配置（上から下に並べる）
-contract -[hidden]down-> component
-component -[hidden]down-> e2e
-
-@enduml
-```
-
-<details>
-<summary>Java 実装例（WireMock）</summary>
-
-```java
-// WireMockを使用したサービス間連携テスト
-@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
-@AutoConfigureWireMock(port = 0)
-class OrderServiceWithInventoryTest {
-
-    @Autowired
-    private TestRestTemplate restTemplate;
-
-    @Value("${wiremock.server.port}")
-    private int wireMockPort;
-
-    @BeforeEach
-    void setUp() {
-        // 在庫サービスのモック設定
-        stubFor(get(urlPathMatching("/api/v1/inventory/.*"))
-            .willReturn(aResponse()
-                .withStatus(200)
-                .withHeader("Content-Type", "application/json")
-                .withBody("""
-                    {
-                        "productId": "PRD-001",
-                        "quantity": 100,
-                        "allocatedQuantity": 0,
-                        "availableQuantity": 100
-                    }
-                    """)));
-
-        stubFor(post(urlPathMatching("/api/v1/inventory/allocate"))
-            .willReturn(aResponse()
-                .withStatus(200)
-                .withHeader("Content-Type", "application/json")
-                .withBody("""
-                    {
-                        "success": true,
-                        "allocationId": "ALLOC-001"
-                    }
-                    """)));
-    }
-
-    @Test
-    @DisplayName("受注確定: 在庫引当成功")
-    void confirmOrder_InventoryAllocated() {
-        // Given
-        String orderId = createDraftOrder();
-
-        // When
-        ResponseEntity<OrderResponse> response = restTemplate.exchange(
-            "/api/v1/sales/orders/{orderId}/confirm",
-            HttpMethod.POST,
-            new HttpEntity<>(createAuthHeaders()),
-            OrderResponse.class,
-            orderId
-        );
-
-        // Then
-        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
-        assertThat(response.getBody().getStatus()).isEqualTo("CONFIRMED");
-
-        // 在庫サービスへの呼び出しを検証
-        verify(postRequestedFor(urlPathEqualTo("/api/v1/inventory/allocate"))
-            .withRequestBody(matchingJsonPath("$.productId", equalTo("PRD-001")))
-            .withRequestBody(matchingJsonPath("$.quantity", equalTo("10"))));
-    }
-
-    @Test
-    @DisplayName("受注確定: 在庫不足")
-    void confirmOrder_InsufficientStock() {
-        // Given - 在庫不足のレスポンスを設定
-        stubFor(post(urlPathMatching("/api/v1/inventory/allocate"))
-            .willReturn(aResponse()
-                .withStatus(200)
-                .withBody("""
-                    {
-                        "success": false,
-                        "errorMessage": "Insufficient stock"
-                    }
-                    """)));
-
-        String orderId = createDraftOrder();
-
-        // When
-        ResponseEntity<ProblemDetail> response = restTemplate.exchange(
-            "/api/v1/sales/orders/{orderId}/confirm",
-            HttpMethod.POST,
-            new HttpEntity<>(createAuthHeaders()),
-            ProblemDetail.class,
-            orderId
-        );
-
-        // Then
-        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CONFLICT);
-        assertThat(response.getBody().getDetail()).contains("在庫不足");
-    }
-
-    @Test
-    @DisplayName("受注確定: 在庫サービスタイムアウト")
-    void confirmOrder_InventoryServiceTimeout() {
-        // Given - タイムアウトをシミュレート
-        stubFor(post(urlPathMatching("/api/v1/inventory/allocate"))
-            .willReturn(aResponse()
-                .withFixedDelay(5000) // 5秒遅延
-                .withStatus(200)));
-
-        String orderId = createDraftOrder();
-
-        // When
-        ResponseEntity<ProblemDetail> response = restTemplate.exchange(
-            "/api/v1/sales/orders/{orderId}/confirm",
-            HttpMethod.POST,
-            new HttpEntity<>(createAuthHeaders()),
-            ProblemDetail.class,
-            orderId
-        );
-
-        // Then - サーキットブレーカーによるフォールバック
-        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.SERVICE_UNAVAILABLE);
-    }
-}
-```
-
-</details>
-
----
-
-## 38.5 まとめ
-
-本章では、API 設計とサービス連携のパターンについて解説しました。
-
-### 学んだこと
-
-1. **API 設計の原則**
-
-   - RESTful API の制約と設計原則
-   - リソース指向設計（名詞ベース、HTTP メソッド）
-   - バージョニング戦略（URI パス推奨）
-
-2. **サービス間通信**
-
-   - 同期通信（REST、gRPC）の使い分け
-   - 非同期通信（メッセージキュー）
-   - サーキットブレーカーによる障害対策
-
-3. **API ゲートウェイ**
-
-   - 認証・認可の一元化（JWT）
-   - レート制限とスロットリング
-   - ログ集約とモニタリング
-
-4. **API インテグレーションテスト**
-
-   - テストコンテナによる統合テスト環境
-   - REST API エンドポイントのテスト
-   - サービス間連携テスト（WireMock）
-
-### API 設計チェックリスト
-
-- [ ] リソースは名詞（複数形）で命名されているか
-- [ ] HTTP メソッドが正しく使用されているか
-- [ ] エラーレスポンスは Problem Detail 形式か
-- [ ] バージョニング戦略が決定されているか
-- [ ] 認証・認可が適切に実装されているか
-- [ ] レート制限が設定されているか
-- [ ] サーキットブレーカーが導入されているか
-- [ ] 統合テストが整備されているか
-
-### 次章の予告
-
-第39章では、データ連携の実装パターンについて解説します。バッチ連携、リアルタイム連携、連携テーブルの設計など、具体的な実装パターンを学びます。
+# 第38章：API 設計とサービス連携
+
+本章では、基幹業務システムにおける API 設計の原則と、サービス間連携のパターンについて解説します。RESTful API の設計、サービス間通信の方式、API ゲートウェイの活用、そしてインテグレーションテストの実践方法を学びます。
+
+---
+
+## 38.1 API 設計の原則
+
+### RESTful API の設計
+
+REST（Representational State Transfer）は、Web API 設計の標準的なアーキテクチャスタイルです。
+
+```plantuml
+@startuml
+title RESTful API の基本原則
+
+rectangle "REST の制約" as constraints {
+    rectangle "クライアント-サーバー" as cs {
+        note right
+          関心の分離
+          独立した進化
+        end note
+    }
+
+    rectangle "ステートレス" as stateless {
+        note right
+          各リクエストは独立
+          セッション状態を保持しない
+        end note
+    }
+
+    rectangle "キャッシュ可能" as cacheable {
+        note right
+          レスポンスにキャッシュ可否を明示
+          パフォーマンス向上
+        end note
+    }
+
+    rectangle "統一インターフェース" as uniform {
+        note right
+          リソース識別（URI）
+          表現によるリソース操作
+          自己記述メッセージ
+          HATEOAS
+        end note
+    }
+
+    rectangle "階層化システム" as layered {
+        note right
+          中間サーバーの追加が可能
+          ロードバランサー、キャッシュ等
+        end note
+    }
+}
+
+@enduml
+```
+
+#### HTTP メソッドとリソース操作
+
+| HTTP メソッド | 操作 | 冪等性 | 安全性 | 使用例 |
+|-------------|-----|-------|-------|-------|
+| GET | 取得 | Yes | Yes | リソースの参照 |
+| POST | 作成 | No | No | 新規リソース作成 |
+| PUT | 置換 | Yes | No | リソース全体の更新 |
+| PATCH | 部分更新 | No | No | リソースの一部更新 |
+| DELETE | 削除 | Yes | No | リソースの削除 |
+
+### リソース指向設計
+
+API はリソース（名詞）を中心に設計し、操作は HTTP メソッドで表現します。
+
+```plantuml
+@startuml
+title リソース指向 API 設計
+
+package "販売管理 API" as sales_api {
+    rectangle "/orders" as orders {
+        rectangle "GET /orders" as get_orders
+        rectangle "POST /orders" as post_order
+        rectangle "GET /orders/{id}" as get_order
+        rectangle "PUT /orders/{id}" as put_order
+        rectangle "DELETE /orders/{id}" as delete_order
+    }
+
+    rectangle "/orders/{id}/lines" as order_lines {
+        rectangle "GET /orders/{id}/lines" as get_lines
+        rectangle "POST /orders/{id}/lines" as post_line
+    }
+
+    rectangle "/customers" as customers {
+        rectangle "GET /customers" as get_customers
+        rectangle "POST /customers" as post_customer
+        rectangle "GET /customers/{id}" as get_customer
+    }
+
+    rectangle "/customers/{id}/orders" as customer_orders {
+        rectangle "GET /customers/{id}/orders" as get_customer_orders
+    }
+}
+
+note bottom of sales_api
+  【設計原則】
+  ・リソースは名詞（複数形）
+  ・操作はHTTPメソッドで表現
+  ・階層構造で関連を表現
+  ・クエリパラメータでフィルタリング
+end note
+
+@enduml
+```
+
+#### 基幹業務システムの API エンドポイント設計
+
+```plantuml
+@startuml
+title 基幹業務システム API エンドポイント
+
+package "販売管理 API" as sales {
+    rectangle "/api/v1/sales" as sales_base {
+        rectangle "受注: /orders"
+        rectangle "出荷: /shipments"
+        rectangle "売上: /sales"
+        rectangle "請求: /invoices"
+        rectangle "入金: /payments"
+    }
+    rectangle "/api/v1/sales/masters" as sales_masters {
+        rectangle "顧客: /customers"
+        rectangle "商品: /products"
+    }
+}
+
+package "財務会計 API" as accounting {
+    rectangle "/api/v1/accounting" as acc_base {
+        rectangle "仕訳: /journals"
+        rectangle "残高: /balances"
+        rectangle "試算表: /trial-balances"
+    }
+    rectangle "/api/v1/accounting/masters" as acc_masters {
+        rectangle "勘定科目: /accounts"
+        rectangle "補助科目: /sub-accounts"
+    }
+}
+
+package "生産管理 API" as production {
+    rectangle "/api/v1/production" as prod_base {
+        rectangle "製造指示: /work-orders"
+        rectangle "発注: /purchase-orders"
+        rectangle "在庫: /inventory"
+    }
+    rectangle "/api/v1/production/masters" as prod_masters {
+        rectangle "品目: /items"
+        rectangle "BOM: /bom"
+        rectangle "工程: /processes"
+    }
+}
+
+@enduml
+```
+
+<details>
+<summary>OpenAPI 定義例</summary>
+
+```yaml
+openapi: 3.0.3
+info:
+  title: 販売管理 API
+  version: 1.0.0
+  description: 基幹業務システム - 販売管理 API
+
+servers:
+  - url: https://api.example.com/api/v1/sales
+    description: Production server
+
+paths:
+  /orders:
+    get:
+      summary: 受注一覧取得
+      operationId: getOrders
+      parameters:
+        - name: customerId
+          in: query
+          schema:
+            type: string
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum: [DRAFT, CONFIRMED, SHIPPED, COMPLETED]
+        - name: fromDate
+          in: query
+          schema:
+            type: string
+            format: date
+        - name: toDate
+          in: query
+          schema:
+            type: string
+            format: date
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 0
+        - name: size
+          in: query
+          schema:
+            type: integer
+            default: 20
+      responses:
+        '200':
+          description: 成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OrderListResponse'
+
+    post:
+      summary: 受注登録
+      operationId: createOrder
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateOrderRequest'
+      responses:
+        '201':
+          description: 作成成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OrderResponse'
+        '400':
+          description: バリデーションエラー
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/ProblemDetail'
+
+  /orders/{orderId}:
+    get:
+      summary: 受注詳細取得
+      operationId: getOrder
+      parameters:
+        - name: orderId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: 成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OrderResponse'
+        '404':
+          description: 受注が見つからない
+
+components:
+  schemas:
+    OrderResponse:
+      type: object
+      properties:
+        orderId:
+          type: string
+        customerId:
+          type: string
+        customerName:
+          type: string
+        orderDate:
+          type: string
+          format: date
+        status:
+          type: string
+          enum: [DRAFT, CONFIRMED, SHIPPED, COMPLETED]
+        totalAmount:
+          type: number
+        taxAmount:
+          type: number
+        lines:
+          type: array
+          items:
+            $ref: '#/components/schemas/OrderLineResponse'
+        _links:
+          $ref: '#/components/schemas/Links'
+
+    CreateOrderRequest:
+      type: object
+      required:
+        - customerId
+        - orderDate
+        - lines
+      properties:
+        customerId:
+          type: string
+        orderDate:
+          type: string
+          format: date
+        requestedDeliveryDate:
+          type: string
+          format: date
+        lines:
+          type: array
+          items:
+            $ref: '#/components/schemas/CreateOrderLineRequest'
+          minItems: 1
+
+    ProblemDetail:
+      type: object
+      properties:
+        type:
+          type: string
+        title:
+          type: string
+        status:
+          type: integer
+        detail:
+          type: string
+        instance:
+          type: string
+```
+
+</details>
+
+### バージョニング戦略
+
+API の互換性を維持しながら進化させるためのバージョニング戦略を検討します。
+
+```plantuml
+@startuml
+title API バージョニング戦略の比較
+
+rectangle "URI パスバージョニング" as uri {
+    note right
+      /api/v1/orders
+      /api/v2/orders
+
+      【メリット】
+      ・明確で分かりやすい
+      ・キャッシュしやすい
+
+      【デメリット】
+      ・URIの変更が必要
+    end note
+}
+
+rectangle "クエリパラメータ" as query {
+    note right
+      /api/orders?version=1
+      /api/orders?version=2
+
+      【メリット】
+      ・URIが変わらない
+
+      【デメリット】
+      ・見落としやすい
+    end note
+}
+
+rectangle "カスタムヘッダー" as header {
+    note right
+      X-API-Version: 1
+      X-API-Version: 2
+
+      【メリット】
+      ・URIがクリーン
+
+      【デメリット】
+      ・テストしにくい
+    end note
+}
+
+rectangle "Accept ヘッダー" as accept {
+    note right
+      Accept: application/vnd.company.v1+json
+      Accept: application/vnd.company.v2+json
+
+      【メリット】
+      ・HTTP標準に準拠
+
+      【デメリット】
+      ・複雑
+    end note
+}
+
+@enduml
+```
+
+#### 推奨：URI パスバージョニング
+
+```plantuml
+@startuml
+title URI パスバージョニングの運用
+
+rectangle "v1（現行）" as v1 {
+    rectangle "/api/v1/orders" as v1_orders
+    rectangle "/api/v1/customers" as v1_customers
+}
+
+rectangle "v2（新版）" as v2 {
+    rectangle "/api/v2/orders" as v2_orders
+    rectangle "/api/v2/customers" as v2_customers
+}
+
+note bottom of v1
+  【v1 → v2 移行】
+  1. v2を新規リリース
+  2. 並行運用期間
+  3. v1を非推奨化（Deprecation）
+  4. v1を廃止（Sunset）
+
+  【Deprecation ヘッダー】
+  Deprecation: true
+  Sunset: Sat, 01 Jan 2025 00:00:00 GMT
+end note
+
+@enduml
+```
+
+---
+
+## 38.2 サービス間通信
+
+### 同期通信（REST / gRPC）
+
+```plantuml
+@startuml
+title 同期通信パターンの比較
+
+rectangle "REST over HTTP" as rest {
+    rectangle "販売サービス" as sales_rest
+    rectangle "在庫サービス" as inv_rest
+
+    sales_rest --> inv_rest : HTTP/JSON
+}
+
+rectangle "gRPC" as grpc {
+    rectangle "販売サービス" as sales_grpc
+    rectangle "在庫サービス" as inv_grpc
+
+    sales_grpc --> inv_grpc : HTTP/2 + Protocol Buffers
+}
+
+note bottom of rest
+  【REST】
+  ・テキストベース（JSON）
+  ・ブラウザから直接呼び出し可能
+  ・広く普及、ツール豊富
+
+  【適用場面】
+  ・外部公開API
+  ・フロントエンド連携
+end note
+
+note bottom of grpc
+  【gRPC】
+  ・バイナリプロトコル
+  ・高速、低レイテンシ
+  ・スキーマ定義必須
+
+  【適用場面】
+  ・マイクロサービス間
+  ・高性能要件
+end note
+
+@enduml
+```
+
+<details>
+<summary>gRPC 定義例</summary>
+
+```protobuf
+syntax = "proto3";
+
+package sales.v1;
+
+option java_package = "com.example.sales.grpc";
+option java_multiple_files = true;
+
+// 在庫サービス
+service InventoryService {
+  // 在庫照会
+  rpc GetStock(GetStockRequest) returns (StockResponse);
+
+  // 在庫引当
+  rpc AllocateStock(AllocateStockRequest) returns (AllocateStockResponse);
+
+  // 引当解除
+  rpc ReleaseStock(ReleaseStockRequest) returns (ReleaseStockResponse);
+}
+
+message GetStockRequest {
+  string product_id = 1;
+  string warehouse_id = 2;
+}
+
+message StockResponse {
+  string product_id = 1;
+  string warehouse_id = 2;
+  int32 quantity = 3;
+  int32 allocated_quantity = 4;
+  int32 available_quantity = 5;
+}
+
+message AllocateStockRequest {
+  string product_id = 1;
+  string warehouse_id = 2;
+  int32 quantity = 3;
+  string order_id = 4;
+}
+
+message AllocateStockResponse {
+  bool success = 1;
+  string allocation_id = 2;
+  string error_message = 3;
+}
+```
+
+</details>
+
+### 非同期通信（メッセージキュー）
+
+```plantuml
+@startuml
+title 非同期通信パターン
+
+rectangle "販売サービス" as sales
+
+rectangle "メッセージブローカー" as broker {
+    queue "受注キュー" as order_queue
+    collections "売上トピック" as sales_topic
+}
+
+rectangle "在庫サービス" as inventory
+rectangle "会計サービス" as accounting
+rectangle "通知サービス" as notification
+
+sales --> order_queue : 受注メッセージ
+order_queue --> inventory : 在庫引当
+
+sales --> sales_topic : 売上イベント
+sales_topic --> accounting : 仕訳生成
+sales_topic --> notification : 通知送信
+sales_topic --> inventory : 在庫更新
+
+note bottom of broker
+  【Point-to-Point】
+  ・1対1の通信
+  ・キューで実現
+  ・負荷分散可能
+
+  【Publish-Subscribe】
+  ・1対多の通信
+  ・トピックで実現
+  ・イベント配信
+end note
+
+@enduml
+```
+
+<details>
+<summary>Java 実装例（Spring AMQP）</summary>
+
+```java
+// メッセージ送信
+@Service
+public class OrderMessagePublisher {
+    private final RabbitTemplate rabbitTemplate;
+
+    public void publishOrderCreated(OrderCreatedEvent event) {
+        rabbitTemplate.convertAndSend(
+            "sales.exchange",
+            "order.created",
+            event
+        );
+    }
+
+    public void publishSalesCompleted(SalesCompletedEvent event) {
+        rabbitTemplate.convertAndSend(
+            "sales.topic.exchange",
+            "sales.completed",
+            event
+        );
+    }
+}
+
+// メッセージ受信
+@Component
+public class OrderMessageListener {
+
+    @RabbitListener(queues = "inventory.order.queue")
+    public void handleOrderCreated(OrderCreatedEvent event) {
+        // 在庫引当処理
+        log.info("Received order: {}", event.orderId());
+        inventoryService.allocate(event);
+    }
+}
+
+// 設定
+@Configuration
+public class RabbitMQConfig {
+
+    @Bean
+    public TopicExchange salesTopicExchange() {
+        return new TopicExchange("sales.topic.exchange");
+    }
+
+    @Bean
+    public Queue accountingQueue() {
+        return new Queue("accounting.sales.queue", true);
+    }
+
+    @Bean
+    public Binding accountingBinding(Queue accountingQueue,
+                                      TopicExchange salesTopicExchange) {
+        return BindingBuilder.bind(accountingQueue)
+            .to(salesTopicExchange)
+            .with("sales.*");
+    }
+}
+```
+
+</details>
+
+### サーキットブレーカーパターン
+
+サービス間通信の障害を検知し、障害の連鎖を防ぐパターンです。
+
+```plantuml
+@startuml
+title サーキットブレーカーの状態遷移
+
+[*] --> Closed : 初期状態
+
+Closed --> Open : 失敗が閾値を超過
+Closed --> Closed : 成功
+
+Open --> HalfOpen : タイムアウト後
+Open --> Open : リクエスト拒否
+
+HalfOpen --> Closed : 試行成功
+HalfOpen --> Open : 試行失敗
+
+note right of Closed
+  【Closed】
+  通常稼働
+  リクエストを通す
+end note
+
+note right of Open
+  【Open】
+  障害検知
+  即座にエラー返却
+  （Fail Fast）
+end note
+
+note right of HalfOpen
+  【Half-Open】
+  復旧確認中
+  限定的に試行
+end note
+
+@enduml
+```
+
+```plantuml
+@startuml
+title サーキットブレーカーの動作フロー
+
+|クライアント|
+start
+:サービス呼び出し;
+
+|サーキットブレーカー|
+if (回路状態?) then (Open)
+    :即座にフォールバック;
+    |クライアント|
+    :フォールバック結果;
+    stop
+else (Closed/HalfOpen)
+endif
+
+:下流サービス呼び出し;
+
+|下流サービス|
+if (処理成功?) then (yes)
+    :正常レスポンス;
+    |サーキットブレーカー|
+    :成功をカウント;
+    :Closedを維持/遷移;
+else (no)
+    :エラー/タイムアウト;
+    |サーキットブレーカー|
+    :失敗をカウント;
+
+    if (失敗数 >= 閾値?) then (yes)
+        :Openに遷移;
+    endif
+endif
+
+|クライアント|
+:結果を返却;
+
+stop
+
+@enduml
+```
+
+<details>
+<summary>Java 実装例（Resilience4j）</summary>
+
+```java
+// 設定
+@Configuration
+public class CircuitBreakerConfig {
+
+    @Bean
+    public CircuitBreakerRegistry circuitBreakerRegistry() {
+        CircuitBreakerConfig config = CircuitBreakerConfig.custom()
+            .failureRateThreshold(50)  // 失敗率50%でOpen
+            .waitDurationInOpenState(Duration.ofSeconds(30))
+            .permittedNumberOfCallsInHalfOpenState(3)
+            .slidingWindowType(SlidingWindowType.COUNT_BASED)
+            .slidingWindowSize(10)
+            .build();
+
+        return CircuitBreakerRegistry.of(config);
+    }
+}
+
+// サービス
+@Service
+public class InventoryServiceClient {
+    private final RestTemplate restTemplate;
+    private final CircuitBreaker circuitBreaker;
+
+    public InventoryServiceClient(RestTemplate restTemplate,
+                                   CircuitBreakerRegistry registry) {
+        this.restTemplate = restTemplate;
+        this.circuitBreaker = registry.circuitBreaker("inventoryService");
+    }
+
+    public StockResponse getStock(String productId) {
+        Supplier<StockResponse> supplier = CircuitBreaker
+            .decorateSupplier(circuitBreaker, () -> {
+                return restTemplate.getForObject(
+                    "/api/v1/inventory/{productId}",
+                    StockResponse.class,
+                    productId
+                );
+            });
+
+        return Try.ofSupplier(supplier)
+            .recover(CallNotPermittedException.class,
+                e -> getFallbackStock(productId))
+            .recover(Exception.class,
+                e -> getFallbackStock(productId))
+            .get();
+    }
+
+    private StockResponse getFallbackStock(String productId) {
+        // フォールバック: キャッシュから取得または推定値
+        return new StockResponse(productId, 0, 0, 0, "UNKNOWN");
+    }
+}
+
+// アノテーションベース
+@Service
+public class AccountingServiceClient {
+
+    @CircuitBreaker(name = "accountingService", fallbackMethod = "fallback")
+    @Retry(name = "accountingService")
+    @TimeLimiter(name = "accountingService")
+    public CompletableFuture<JournalResponse> createJournal(
+            CreateJournalRequest request) {
+        return CompletableFuture.supplyAsync(() -> {
+            return restTemplate.postForObject(
+                "/api/v1/accounting/journals",
+                request,
+                JournalResponse.class
+            );
+        });
+    }
+
+    public CompletableFuture<JournalResponse> fallback(
+            CreateJournalRequest request, Throwable t) {
+        log.warn("Fallback for createJournal: {}", t.getMessage());
+        // 仕訳をキューに保存して後で再試行
+        pendingJournalQueue.add(request);
+        return CompletableFuture.completedFuture(
+            JournalResponse.pending(request.getCorrelationId())
+        );
+    }
+}
+```
+
+</details>
+
+---
+
+## 38.3 API ゲートウェイ
+
+API ゲートウェイは、クライアントと複数のバックエンドサービスの間に位置し、横断的な関心事を一元的に処理します。
+
+```plantuml
+@startuml
+title API ゲートウェイアーキテクチャ
+
+rectangle "クライアント" as clients {
+    rectangle "Webアプリ" as web
+    rectangle "モバイルアプリ" as mobile
+    rectangle "外部システム" as external
+}
+
+rectangle "API Gateway" as gateway {
+    rectangle "認証・認可" as auth
+    rectangle "レート制限" as rate
+    rectangle "ルーティング" as routing
+    rectangle "ログ・監視" as logging
+    rectangle "変換・集約" as transform
+}
+
+rectangle "バックエンドサービス" as backend {
+    rectangle "販売API" as sales
+    rectangle "会計API" as accounting
+    rectangle "生産API" as production
+}
+
+web --> gateway
+mobile --> gateway
+external --> gateway
+
+gateway --> sales
+gateway --> accounting
+gateway --> production
+
+note bottom of gateway
+  【API Gatewayの責務】
+  ・認証・認可の一元化
+  ・レート制限
+  ・リクエストルーティング
+  ・ログ集約
+  ・レスポンス変換
+  ・API集約
+end note
+
+@enduml
+```
+
+### 認証・認可の一元化
+
+```plantuml
+@startuml
+title JWT 認証フロー
+
+|クライアント|
+start
+:認証リクエスト;
+note right
+  POST /auth/login
+  {username, password}
+end note
+
+|認証サービス|
+:認証情報検証;
+:JWTトークン発行;
+note right
+  Header: {alg, typ}
+  Payload: {sub, roles, exp}
+  Signature
+end note
+
+|クライアント|
+:JWTトークン保存;
+:API呼び出し;
+note right
+  Authorization: Bearer {token}
+end note
+
+|API Gateway|
+:JWTトークン検証;
+if (有効?) then (yes)
+    :クレーム抽出;
+    :認可チェック;
+    if (権限あり?) then (yes)
+        |バックエンドサービス|
+        :リクエスト処理;
+        :レスポンス返却;
+    else (no)
+        :403 Forbidden;
+    endif
+else (no)
+    :401 Unauthorized;
+endif
+
+|クライアント|
+:結果受信;
+
+stop
+
+@enduml
+```
+
+<details>
+<summary>Java 実装例（Spring Security + JWT）</summary>
+
+```java
+// JWT フィルター
+@Component
+public class JwtAuthenticationFilter extends OncePerRequestFilter {
+    private final JwtTokenProvider tokenProvider;
+
+    @Override
+    protected void doFilterInternal(HttpServletRequest request,
+                                     HttpServletResponse response,
+                                     FilterChain filterChain)
+            throws ServletException, IOException {
+
+        String token = extractToken(request);
+
+        if (token != null && tokenProvider.validateToken(token)) {
+            Authentication auth = tokenProvider.getAuthentication(token);
+            SecurityContextHolder.getContext().setAuthentication(auth);
+        }
+
+        filterChain.doFilter(request, response);
+    }
+
+    private String extractToken(HttpServletRequest request) {
+        String bearerToken = request.getHeader("Authorization");
+        if (bearerToken != null && bearerToken.startsWith("Bearer ")) {
+            return bearerToken.substring(7);
+        }
+        return null;
+    }
+}
+
+// JWT プロバイダー
+@Component
+public class JwtTokenProvider {
+    @Value("${jwt.secret}")
+    private String jwtSecret;
+
+    @Value("${jwt.expiration}")
+    private long jwtExpiration;
+
+    public String generateToken(Authentication authentication) {
+        UserDetails userDetails = (UserDetails) authentication.getPrincipal();
+
+        return Jwts.builder()
+            .setSubject(userDetails.getUsername())
+            .claim("roles", userDetails.getAuthorities().stream()
+                .map(GrantedAuthority::getAuthority)
+                .collect(Collectors.toList()))
+            .setIssuedAt(new Date())
+            .setExpiration(new Date(System.currentTimeMillis() + jwtExpiration))
+            .signWith(SignatureAlgorithm.HS512, jwtSecret)
+            .compact();
+    }
+
+    public boolean validateToken(String token) {
+        try {
+            Jwts.parser().setSigningKey(jwtSecret).parseClaimsJws(token);
+            return true;
+        } catch (JwtException | IllegalArgumentException e) {
+            return false;
+        }
+    }
+
+    public Authentication getAuthentication(String token) {
+        Claims claims = Jwts.parser()
+            .setSigningKey(jwtSecret)
+            .parseClaimsJws(token)
+            .getBody();
+
+        List<String> roles = claims.get("roles", List.class);
+        List<GrantedAuthority> authorities = roles.stream()
+            .map(SimpleGrantedAuthority::new)
+            .collect(Collectors.toList());
+
+        User principal = new User(claims.getSubject(), "", authorities);
+        return new UsernamePasswordAuthenticationToken(
+            principal, token, authorities
+        );
+    }
+}
+```
+
+</details>
+
+### レート制限とスロットリング
+
+```plantuml
+@startuml
+title レート制限アルゴリズム
+
+rectangle "Token Bucket" as token_bucket {
+    note right
+      ・バケットにトークンを蓄積
+      ・リクエスト時にトークン消費
+      ・バースト対応可能
+
+      設定例:
+      rate: 100/分
+      burst: 20
+    end note
+}
+
+rectangle "Sliding Window" as sliding_window {
+    note right
+      ・時間枠内のリクエスト数をカウント
+      ・枠をスライドして計算
+      ・より正確な制限
+
+      設定例:
+      window: 1分
+      limit: 100
+    end note
+}
+
+rectangle "Fixed Window" as fixed_window {
+    note right
+      ・固定時間枠でカウント
+      ・シンプルな実装
+      ・境界でバーストの可能性
+
+      設定例:
+      window: 1分
+      limit: 100
+    end note
+}
+
+@enduml
+```
+
+<details>
+<summary>Spring Cloud Gateway 設定例</summary>
+
+```yaml
+# application.yml
+spring:
+  cloud:
+    gateway:
+      routes:
+        - id: sales-service
+          uri: lb://sales-service
+          predicates:
+            - Path=/api/v1/sales/**
+          filters:
+            - name: RequestRateLimiter
+              args:
+                redis-rate-limiter.replenishRate: 100
+                redis-rate-limiter.burstCapacity: 200
+                key-resolver: "#{@userKeyResolver}"
+            - name: CircuitBreaker
+              args:
+                name: salesCircuitBreaker
+                fallbackUri: forward:/fallback/sales
+
+        - id: accounting-service
+          uri: lb://accounting-service
+          predicates:
+            - Path=/api/v1/accounting/**
+          filters:
+            - name: RequestRateLimiter
+              args:
+                redis-rate-limiter.replenishRate: 50
+                redis-rate-limiter.burstCapacity: 100
+
+      default-filters:
+        - name: Retry
+          args:
+            retries: 3
+            statuses: BAD_GATEWAY,SERVICE_UNAVAILABLE
+            methods: GET
+            backoff:
+              firstBackoff: 100ms
+              maxBackoff: 500ms
+              factor: 2
+```
+
+```java
+// Key Resolver（ユーザー単位のレート制限）
+@Configuration
+public class RateLimiterConfig {
+
+    @Bean
+    public KeyResolver userKeyResolver() {
+        return exchange -> {
+            String userId = exchange.getRequest()
+                .getHeaders()
+                .getFirst("X-User-Id");
+            return Mono.just(userId != null ? userId : "anonymous");
+        };
+    }
+
+    @Bean
+    public KeyResolver apiKeyResolver() {
+        return exchange -> {
+            String apiKey = exchange.getRequest()
+                .getHeaders()
+                .getFirst("X-API-Key");
+            return Mono.just(apiKey != null ? apiKey : "default");
+        };
+    }
+}
+```
+
+</details>
+
+### ログ集約とモニタリング
+
+```plantuml
+@startuml
+title 分散トレーシングとログ集約
+
+rectangle "クライアント" as client
+
+rectangle "API Gateway" as gateway {
+    rectangle "トレースID生成" as trace_gen
+}
+
+rectangle "サービス群" as services {
+    rectangle "販売サービス" as sales
+    rectangle "在庫サービス" as inventory
+    rectangle "会計サービス" as accounting
+}
+
+rectangle "観測基盤" as observability {
+    database "ログ集約\n(ELK/Loki)" as logs
+    database "メトリクス\n(Prometheus)" as metrics
+    database "トレース\n(Jaeger/Zipkin)" as traces
+}
+
+rectangle "ダッシュボード" as dashboard {
+    rectangle "Grafana" as grafana
+    rectangle "Kibana" as kibana
+}
+
+client --> gateway : リクエスト
+gateway --> sales : traceId
+sales --> inventory : traceId
+sales --> accounting : traceId
+
+gateway --> logs
+sales --> logs
+inventory --> logs
+accounting --> logs
+
+gateway --> metrics
+sales --> metrics
+inventory --> metrics
+accounting --> metrics
+
+gateway --> traces
+sales --> traces
+inventory --> traces
+accounting --> traces
+
+logs --> kibana
+metrics --> grafana
+traces --> grafana
+
+@enduml
+```
+
+<details>
+<summary>Java 実装例（Micrometer + OpenTelemetry）</summary>
+
+```java
+// トレーシング設定
+@Configuration
+public class TracingConfig {
+
+    @Bean
+    public Tracer tracer() {
+        return GlobalOpenTelemetry.getTracer("sales-service");
+    }
+}
+
+// カスタムメトリクス
+@Component
+public class OrderMetrics {
+    private final MeterRegistry meterRegistry;
+    private final Counter orderCreatedCounter;
+    private final Timer orderProcessingTimer;
+
+    public OrderMetrics(MeterRegistry meterRegistry) {
+        this.meterRegistry = meterRegistry;
+
+        this.orderCreatedCounter = Counter.builder("orders.created")
+            .description("Number of orders created")
+            .tag("service", "sales")
+            .register(meterRegistry);
+
+        this.orderProcessingTimer = Timer.builder("orders.processing.time")
+            .description("Order processing time")
+            .tag("service", "sales")
+            .register(meterRegistry);
+    }
+
+    public void recordOrderCreated(String status) {
+        orderCreatedCounter.increment();
+        meterRegistry.counter("orders.created.by.status",
+            "status", status).increment();
+    }
+
+    public void recordProcessingTime(long durationMs) {
+        orderProcessingTimer.record(Duration.ofMillis(durationMs));
+    }
+}
+
+// 構造化ログ
+@Slf4j
+@Service
+public class OrderService {
+
+    public Order createOrder(CreateOrderRequest request) {
+        MDC.put("orderId", request.getOrderId());
+        MDC.put("customerId", request.getCustomerId());
+
+        try {
+            log.info("Creating order", kv("action", "create_order_start"));
+
+            Order order = processOrder(request);
+
+            log.info("Order created successfully",
+                kv("action", "create_order_complete"),
+                kv("totalAmount", order.getTotalAmount()));
+
+            return order;
+        } catch (Exception e) {
+            log.error("Failed to create order",
+                kv("action", "create_order_failed"),
+                kv("error", e.getMessage()), e);
+            throw e;
+        } finally {
+            MDC.clear();
+        }
+    }
+}
+```
+
+</details>
+
+---
+
+## 38.4 API インテグレーションテスト
+
+### テストコンテナによる統合テスト環境
+
+```plantuml
+@startuml
+title テストコンテナアーキテクチャ
+
+rectangle "テスト実行環境" as test_env {
+    rectangle "JUnit 5" as junit
+    rectangle "テストクラス" as test_class
+}
+
+rectangle "Testcontainers" as testcontainers {
+    rectangle "PostgreSQL\nコンテナ" as postgres
+    rectangle "RabbitMQ\nコンテナ" as rabbitmq
+    rectangle "Redis\nコンテナ" as redis
+}
+
+rectangle "アプリケーション" as app {
+    rectangle "Spring Boot\nアプリケーション" as spring
+}
+
+test_class --> spring : HTTP リクエスト
+spring --> postgres : データアクセス
+spring --> rabbitmq : メッセージング
+spring --> redis : キャッシュ
+
+junit --> testcontainers : コンテナ起動
+testcontainers --> postgres
+testcontainers --> rabbitmq
+testcontainers --> redis
+
+note bottom of testcontainers
+  【Testcontainersの利点】
+  ・本番同等の環境でテスト
+  ・テスト間の分離
+  ・CI/CDでの再現性
+  ・自動クリーンアップ
+end note
+
+@enduml
+```
+
+<details>
+<summary>Java 実装例</summary>
+
+```java
+// テストコンテナ設定
+@Testcontainers
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@ActiveProfiles("test")
+public abstract class IntegrationTestBase {
+
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15")
+        .withDatabaseName("testdb")
+        .withUsername("test")
+        .withPassword("test");
+
+    @Container
+    static RabbitMQContainer rabbitmq = new RabbitMQContainer("rabbitmq:3.12-management");
+
+    @DynamicPropertySource
+    static void configureProperties(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", postgres::getJdbcUrl);
+        registry.add("spring.datasource.username", postgres::getUsername);
+        registry.add("spring.datasource.password", postgres::getPassword);
+        registry.add("spring.rabbitmq.host", rabbitmq::getHost);
+        registry.add("spring.rabbitmq.port", rabbitmq::getAmqpPort);
+    }
+
+    @Autowired
+    protected TestRestTemplate restTemplate;
+
+    @Autowired
+    protected JdbcTemplate jdbcTemplate;
+
+    @BeforeEach
+    void setUp() {
+        // テストデータのクリーンアップ
+        cleanupTestData();
+    }
+
+    protected void cleanupTestData() {
+        jdbcTemplate.execute("TRUNCATE TABLE 受注明細 CASCADE");
+        jdbcTemplate.execute("TRUNCATE TABLE 受注 CASCADE");
+    }
+}
+```
+
+</details>
+
+### REST API エンドポイントのテスト
+
+```plantuml
+@startuml
+title API テストの構造
+
+' ノード間の間隔を調整
+skinparam nodesep 50
+skinparam ranksep 50
+
+rectangle "== Given（前提条件）\n\n・テストデータ準備\n・認証トークン取得\n・モックの設定" as given
+
+rectangle "== When（操作）\n\n・APIエンドポイント呼び出し\n・リクエストボディ設定\n・ヘッダー設定" as when
+
+rectangle "== Then（検証）\n\n・ステータスコード確認\n・レスポンスボディ検証\n・データベース状態確認\n・イベント発行確認" as then
+
+given --> when
+when --> then
+
+@enduml
+```
+
+<details>
+<summary>Java 実装例</summary>
+
+```java
+// 受注API統合テスト
+class OrderApiIntegrationTest extends IntegrationTestBase {
+
+    @Autowired
+    private CustomerRepository customerRepository;
+
+    @Autowired
+    private ProductRepository productRepository;
+
+    private String authToken;
+    private Customer testCustomer;
+    private Product testProduct;
+
+    @BeforeEach
+    void setUpTestData() {
+        // 認証トークン取得
+        authToken = getAuthToken("test-user", "password");
+
+        // テストデータ準備
+        testCustomer = customerRepository.save(
+            new Customer("CUS-001", "テスト顧客", "test@example.com")
+        );
+        testProduct = productRepository.save(
+            new Product("PRD-001", "テスト商品", new BigDecimal("1000"))
+        );
+    }
+
+    @Test
+    @DisplayName("受注登録: 正常系")
+    void createOrder_Success() {
+        // Given
+        CreateOrderRequest request = CreateOrderRequest.builder()
+            .customerId(testCustomer.getCustomerId())
+            .orderDate(LocalDate.now())
+            .lines(List.of(
+                OrderLineRequest.builder()
+                    .productId(testProduct.getProductId())
+                    .quantity(10)
+                    .build()
+            ))
+            .build();
+
+        // When
+        ResponseEntity<OrderResponse> response = restTemplate.exchange(
+            "/api/v1/sales/orders",
+            HttpMethod.POST,
+            new HttpEntity<>(request, createAuthHeaders()),
+            OrderResponse.class
+        );
+
+        // Then
+        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED);
+        assertThat(response.getBody()).isNotNull();
+        assertThat(response.getBody().getOrderId()).isNotBlank();
+        assertThat(response.getBody().getStatus()).isEqualTo("DRAFT");
+        assertThat(response.getBody().getTotalAmount())
+            .isEqualByComparingTo(new BigDecimal("10000"));
+
+        // データベース状態確認
+        Order savedOrder = orderRepository.findById(
+            response.getBody().getOrderId()
+        ).orElseThrow();
+        assertThat(savedOrder.getCustomerId()).isEqualTo(testCustomer.getCustomerId());
+        assertThat(savedOrder.getLines()).hasSize(1);
+    }
+
+    @Test
+    @DisplayName("受注登録: バリデーションエラー")
+    void createOrder_ValidationError() {
+        // Given - 明細なしのリクエスト
+        CreateOrderRequest request = CreateOrderRequest.builder()
+            .customerId(testCustomer.getCustomerId())
+            .orderDate(LocalDate.now())
+            .lines(List.of()) // 空の明細
+            .build();
+
+        // When
+        ResponseEntity<ProblemDetail> response = restTemplate.exchange(
+            "/api/v1/sales/orders",
+            HttpMethod.POST,
+            new HttpEntity<>(request, createAuthHeaders()),
+            ProblemDetail.class
+        );
+
+        // Then
+        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.BAD_REQUEST);
+        assertThat(response.getBody().getTitle()).isEqualTo("Validation Error");
+    }
+
+    @Test
+    @DisplayName("受注一覧取得: ページング")
+    void getOrders_Paging() {
+        // Given - 複数の受注を作成
+        for (int i = 0; i < 25; i++) {
+            createTestOrder("ORD-" + String.format("%03d", i));
+        }
+
+        // When
+        ResponseEntity<PagedResponse<OrderSummary>> response = restTemplate.exchange(
+            "/api/v1/sales/orders?page=0&size=10",
+            HttpMethod.GET,
+            new HttpEntity<>(createAuthHeaders()),
+            new ParameterizedTypeReference<>() {}
+        );
+
+        // Then
+        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
+        assertThat(response.getBody().getContent()).hasSize(10);
+        assertThat(response.getBody().getTotalElements()).isEqualTo(25);
+        assertThat(response.getBody().getTotalPages()).isEqualTo(3);
+    }
+
+    private HttpHeaders createAuthHeaders() {
+        HttpHeaders headers = new HttpHeaders();
+        headers.setBearerAuth(authToken);
+        headers.setContentType(MediaType.APPLICATION_JSON);
+        return headers;
+    }
+}
+```
+
+</details>
+
+### サービス間連携テスト
+
+```plantuml
+@startuml
+title サービス間連携テストのアプローチ
+
+' ボックスの定義
+rectangle "Contract Testing" as contract
+note right of contract
+  ・Pact / Spring Cloud Contract
+  ・プロバイダーとコンシューマーの契約
+  ・独立したテスト実行
+end note
+
+rectangle "Component Testing" as component
+note right of component
+  ・WireMockで外部サービスをモック
+  ・単一サービスの統合テスト
+  ・高速なフィードバック
+end note
+
+rectangle "End-to-End Testing" as e2e
+note right of e2e
+  ・全サービスを起動
+  ・Docker Composeで環境構築
+  ・本番同等のシナリオテスト
+end note
+
+' 配置（上から下に並べる）
+contract -[hidden]down-> component
+component -[hidden]down-> e2e
+
+@enduml
+```
+
+<details>
+<summary>Java 実装例（WireMock）</summary>
+
+```java
+// WireMockを使用したサービス間連携テスト
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@AutoConfigureWireMock(port = 0)
+class OrderServiceWithInventoryTest {
+
+    @Autowired
+    private TestRestTemplate restTemplate;
+
+    @Value("${wiremock.server.port}")
+    private int wireMockPort;
+
+    @BeforeEach
+    void setUp() {
+        // 在庫サービスのモック設定
+        stubFor(get(urlPathMatching("/api/v1/inventory/.*"))
+            .willReturn(aResponse()
+                .withStatus(200)
+                .withHeader("Content-Type", "application/json")
+                .withBody("""
+                    {
+                        "productId": "PRD-001",
+                        "quantity": 100,
+                        "allocatedQuantity": 0,
+                        "availableQuantity": 100
+                    }
+                    """)));
+
+        stubFor(post(urlPathMatching("/api/v1/inventory/allocate"))
+            .willReturn(aResponse()
+                .withStatus(200)
+                .withHeader("Content-Type", "application/json")
+                .withBody("""
+                    {
+                        "success": true,
+                        "allocationId": "ALLOC-001"
+                    }
+                    """)));
+    }
+
+    @Test
+    @DisplayName("受注確定: 在庫引当成功")
+    void confirmOrder_InventoryAllocated() {
+        // Given
+        String orderId = createDraftOrder();
+
+        // When
+        ResponseEntity<OrderResponse> response = restTemplate.exchange(
+            "/api/v1/sales/orders/{orderId}/confirm",
+            HttpMethod.POST,
+            new HttpEntity<>(createAuthHeaders()),
+            OrderResponse.class,
+            orderId
+        );
+
+        // Then
+        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
+        assertThat(response.getBody().getStatus()).isEqualTo("CONFIRMED");
+
+        // 在庫サービスへの呼び出しを検証
+        verify(postRequestedFor(urlPathEqualTo("/api/v1/inventory/allocate"))
+            .withRequestBody(matchingJsonPath("$.productId", equalTo("PRD-001")))
+            .withRequestBody(matchingJsonPath("$.quantity", equalTo("10"))));
+    }
+
+    @Test
+    @DisplayName("受注確定: 在庫不足")
+    void confirmOrder_InsufficientStock() {
+        // Given - 在庫不足のレスポンスを設定
+        stubFor(post(urlPathMatching("/api/v1/inventory/allocate"))
+            .willReturn(aResponse()
+                .withStatus(200)
+                .withBody("""
+                    {
+                        "success": false,
+                        "errorMessage": "Insufficient stock"
+                    }
+                    """)));
+
+        String orderId = createDraftOrder();
+
+        // When
+        ResponseEntity<ProblemDetail> response = restTemplate.exchange(
+            "/api/v1/sales/orders/{orderId}/confirm",
+            HttpMethod.POST,
+            new HttpEntity<>(createAuthHeaders()),
+            ProblemDetail.class,
+            orderId
+        );
+
+        // Then
+        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CONFLICT);
+        assertThat(response.getBody().getDetail()).contains("在庫不足");
+    }
+
+    @Test
+    @DisplayName("受注確定: 在庫サービスタイムアウト")
+    void confirmOrder_InventoryServiceTimeout() {
+        // Given - タイムアウトをシミュレート
+        stubFor(post(urlPathMatching("/api/v1/inventory/allocate"))
+            .willReturn(aResponse()
+                .withFixedDelay(5000) // 5秒遅延
+                .withStatus(200)));
+
+        String orderId = createDraftOrder();
+
+        // When
+        ResponseEntity<ProblemDetail> response = restTemplate.exchange(
+            "/api/v1/sales/orders/{orderId}/confirm",
+            HttpMethod.POST,
+            new HttpEntity<>(createAuthHeaders()),
+            ProblemDetail.class,
+            orderId
+        );
+
+        // Then - サーキットブレーカーによるフォールバック
+        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.SERVICE_UNAVAILABLE);
+    }
+}
+```
+
+</details>
+
+---
+
+## 38.5 まとめ
+
+本章では、API 設計とサービス連携のパターンについて解説しました。
+
+### 学んだこと
+
+1. **API 設計の原則**
+
+   - RESTful API の制約と設計原則
+   - リソース指向設計（名詞ベース、HTTP メソッド）
+   - バージョニング戦略（URI パス推奨）
+
+2. **サービス間通信**
+
+   - 同期通信（REST、gRPC）の使い分け
+   - 非同期通信（メッセージキュー）
+   - サーキットブレーカーによる障害対策
+
+3. **API ゲートウェイ**
+
+   - 認証・認可の一元化（JWT）
+   - レート制限とスロットリング
+   - ログ集約とモニタリング
+
+4. **API インテグレーションテスト**
+
+   - テストコンテナによる統合テスト環境
+   - REST API エンドポイントのテスト
+   - サービス間連携テスト（WireMock）
+
+### API 設計チェックリスト
+
+- [ ] リソースは名詞（複数形）で命名されているか
+- [ ] HTTP メソッドが正しく使用されているか
+- [ ] エラーレスポンスは Problem Detail 形式か
+- [ ] バージョニング戦略が決定されているか
+- [ ] 認証・認可が適切に実装されているか
+- [ ] レート制限が設定されているか
+- [ ] サーキットブレーカーが導入されているか
+- [ ] 統合テストが整備されているか
+
+### 次章の予告
+
+第39章では、データ連携の実装パターンについて解説します。バッチ連携、リアルタイム連携、連携テーブルの設計など、具体的な実装パターンを学びます。