@k2works/claude-code-booster 2.7.1 → 3.1.0

package/lib/assets/docs/article/functional-desgin-ppp/fsharp/21-best-practices.md

@@ -0,0 +1,320 @@
+# 第21章: 関数型デザインのベストプラクティス
+
+## はじめに
+
+本章では、関数型プログラミングにおける設計のベストプラクティスを体系的に解説します。これらの原則は、保守性が高く、テストしやすい、堅牢なソフトウェアを構築するための指針となります。
+
+### 学習目標
+
+- データ中心設計の原則を理解する
+- 純粋関数と副作用の分離方法を学ぶ
+- テスト可能な設計パターンを習得する
+
+## 1. データ中心設計
+
+### 基本原則
+
+関数型プログラミングでは、**データが主役**です。まずデータ構造を設計し、そのデータを変換する関数を実装します。
+
+```plantuml
+@startuml
+title データ中心設計
+
+rectangle "データ構造" as data {
+  card "User" as user
+  card "Order" as order
+  card "OrderItem" as item
+}
+
+rectangle "変換関数" as funcs {
+  card "calculate" as calc
+  card "validate" as valid
+  card "transform" as trans
+}
+
+rectangle "副作用" as effects {
+  card "DB" as db
+  card "API" as api
+  card "File" as file
+}
+
+data --> funcs : 入力
+funcs --> data : 出力
+funcs --> effects : 境界で実行
+
+@enduml
+```
+
+### データ構造の定義
+
+```fsharp
+/// ユーザー
+type User =
+    { Id: string
+      Name: string
+      Email: string
+      CreatedAt: System.DateTime }
+
+/// 注文
+type Order =
+    { Id: string
+      UserId: string
+      Items: OrderItem list
+      Status: OrderStatus
+      CreatedAt: System.DateTime }
+
+and OrderItem =
+    { ProductId: string
+      Quantity: int
+      Price: decimal }
+
+and OrderStatus =
+    | Pending
+    | Confirmed
+    | Shipped
+    | Delivered
+    | Cancelled
+```
+
+**ポイント**:
+- プレーンなレコードを使用（クラスではなく）
+- 必要最小限のフィールド
+- 明確な命名
+
+### 小さな純粋関数
+
+```fsharp
+module Order =
+    // 各関数は単一の責任を持つ
+    let calculateItemTotal (item: OrderItem) =
+        decimal item.Quantity * item.Price
+
+    let calculateTotal (order: Order) =
+        order.Items |> List.sumBy calculateItemTotal
+
+    let applyDiscount (rate: decimal) (total: decimal) =
+        total * (1m - rate)
+```
+
+**原則**:
+- 1つの関数は1つのことを行う
+- 入力から出力への純粋な変換
+- 副作用なし
+
+## 2. パイプライン処理
+
+### データ変換パイプライン
+
+```fsharp
+module Pipeline =
+    /// 注文処理パイプライン
+    let processOrder (discountRate: decimal) (order: Order) =
+        order
+        |> Order.calculateTotal
+        |> Order.applyDiscount discountRate
+
+    /// 注文ステータスの遷移
+    let confirm (order: Order) =
+        { order with Status = Confirmed }
+
+    let ship (order: Order) =
+        match order.Status with
+        | Confirmed -> { order with Status = Shipped }
+        | _ -> order
+
+    let deliver (order: Order) =
+        match order.Status with
+        | Shipped -> { order with Status = Delivered }
+        | _ -> order
+```
+
+### 使用例
+
+```fsharp
+let order = Order.create "O001" "U001" items
+
+let finalPrice =
+    order
+    |> Pipeline.processOrder 0.10m
+
+let shippedOrder =
+    order
+    |> Pipeline.confirm
+    |> Pipeline.ship
+```
+
+## 3. Result 型によるエラーハンドリング
+
+### バリデーション
+
+```fsharp
+module Validation =
+    type ValidationError =
+        | InvalidEmail of string
+        | InvalidName of string
+        | InvalidQuantity of string
+        | InvalidPrice of string
+
+    let validateEmail (email: string) : Result<string, ValidationError> =
+        if email.Contains("@") then Ok email
+        else Error (InvalidEmail "Email must contain @")
+
+    let validateName (name: string) : Result<string, ValidationError> =
+        if String.length name >= 2 then Ok name
+        else Error (InvalidName "Name must be at least 2 characters")
+
+    let validateQuantity (qty: int) : Result<int, ValidationError> =
+        if qty > 0 then Ok qty
+        else Error (InvalidQuantity "Quantity must be positive")
+```
+
+### Result の連鎖
+
+```fsharp
+    /// Result を連鎖させるヘルパー
+    let bind (f: 'a -> Result<'b, 'e>) (result: Result<'a, 'e>) : Result<'b, 'e> =
+        match result with
+        | Ok v -> f v
+        | Error e -> Error e
+
+    /// 複数の検証を組み合わせる
+    let validateOrderItem (productId: string) (qty: int) (price: decimal) =
+        validateQuantity qty
+        |> bind (fun q ->
+            validatePrice price
+            |> Result.map (fun p -> { ProductId = productId; Quantity = q; Price = p }))
+```
+
+## 4. 副作用の分離
+
+### 純粋な計算部分
+
+```fsharp
+/// 純粋関数（副作用なし）
+module Pure =
+    let calculateTax (rate: decimal) (amount: decimal) =
+        amount * rate
+
+    let formatCurrency (amount: decimal) =
+        sprintf "$%.2f" amount
+
+    let generateInvoiceText (order: Order) (total: decimal) (tax: decimal) =
+        let lines =
+            order.Items
+            |> List.map (fun item ->
+                sprintf "%s x %d @ $%.2f = $%.2f"
+                    item.ProductId item.Quantity item.Price
+                    (decimal item.Quantity * item.Price))
+        let header = sprintf "Invoice for Order %s" order.Id
+        let subtotal = sprintf "Subtotal: $%.2f" total
+        let taxLine = sprintf "Tax: $%.2f" tax
+        let totalLine = sprintf "Total: $%.2f" (total + tax)
+        String.concat "\n" (header :: lines @ [subtotal; taxLine; totalLine])
+```
+
+### 副作用を持つ部分（境界）
+
+```fsharp
+/// 副作用を持つ部分（システムの境界に配置）
+module Effects =
+    /// ログ出力（副作用）
+    let log (message: string) =
+        printfn "[LOG] %s" message
+
+    /// 通知送信（副作用）
+    type Notification =
+        { Recipient: string
+          Subject: string
+          Body: string }
+
+    let sendNotification (notification: Notification) =
+        printfn "[NOTIFICATION] To: %s, Subject: %s"
+            notification.Recipient notification.Subject
+```
+
+### 構造図
+
+```plantuml
+@startuml
+title 副作用の分離
+
+rectangle "Pure Core" as pure {
+  card "calculateTax" as calc
+  card "formatCurrency" as format
+  card "generateInvoiceText" as gen
+}
+
+rectangle "Effects Shell" as effects {
+  card "log" as log
+  card "sendNotification" as notify
+  card "saveToDatabase" as save
+}
+
+rectangle "Orchestration" as orch {
+  card "processOrderUseCase" as usecase
+}
+
+pure --> orch : 純粋な計算
+effects --> orch : 副作用の実行
+orch --> pure : 呼び出し
+orch --> effects : 呼び出し
+
+note bottom of pure
+  テストしやすい
+  並行処理に適している
+  再利用しやすい
+end note
+
+note bottom of effects
+  モック可能
+  境界に配置
+  最小限に保つ
+end note
+@enduml
+```
+
+## 5. テスト可能な設計
+
+### 原則
+
+1. **純粋関数を増やす**: テストが簡単
+2. **依存性を注入**: モック可能
+3. **小さな関数**: 単体テストが容易
+
+### テスト例
+
+```fsharp
+[<Fact>]
+let ``注文の合計金額を計算できる`` () =
+    let items = [
+        { ProductId = "P001"; Quantity = 2; Price = 100m }
+        { ProductId = "P002"; Quantity = 3; Price = 50m }
+    ]
+    let order = Order.create "O001" "U001" items
+    let total = Order.calculateTotal order
+    Assert.Equal(350m, total)
+
+[<Fact>]
+let ``有効なメールアドレスを検証できる`` () =
+    let result = Validation.validateEmail "test@example.com"
+    Assert.True(Result.isOk result)
+```
+
+## まとめ
+
+本章では、関数型デザインのベストプラクティスを学びました：
+
+1. **データ中心設計**: データ構造を先に、関数を後に
+2. **パイプライン処理**: `|>` でデータを変換
+3. **Result 型**: エラーを値として扱う
+4. **副作用の分離**: 純粋な計算とシェルの分離
+5. **テスト可能な設計**: 純粋関数と依存性注入
+
+これらの原則に従うことで、保守性が高く、テストしやすいコードを書くことができます。
+
+## 参考コード
+
+本章のコード例は以下のファイルで確認できます：
+
+- ソースコード: `apps/fsharp/part7/src/Library.fs`
+- テストコード: `apps/fsharp/part7/tests/Tests.fs`

package/lib/assets/docs/article/functional-desgin-ppp/fsharp/22-oo-to-fp-migration.md

@@ -0,0 +1,322 @@
+# 第22章: オブジェクト指向から関数型への移行
+
+## はじめに
+
+本章では、オブジェクト指向（OO）スタイルのコードを関数型（FP）スタイルに移行するための戦略とテクニックを解説します。段階的なアプローチにより、既存のコードベースを安全に関数型に移行できます。
+
+### 学習目標
+
+- OO と FP の根本的な違いを理解する
+- 段階的な移行戦略を学ぶ
+- 実践的なリファクタリングパターンを習得する
+
+## 1. OO と FP の対比
+
+### パラダイムの違い
+
+```plantuml
+@startuml
+title OO vs FP
+
+rectangle "オブジェクト指向" as oo {
+  card "オブジェクト" as obj
+  card "メソッド" as method
+  card "可変状態" as mutable
+  card "継承" as inherit
+}
+
+rectangle "関数型" as fp {
+  card "データ" as data
+  card "関数" as func
+  card "不変性" as immutable
+  card "合成" as compose
+}
+
+obj --> data : 変換
+method --> func : 変換
+mutable --> immutable : 変換
+inherit --> compose : 変換
+@enduml
+```
+
+| 概念 | オブジェクト指向 | 関数型 |
+|-----|----------------|-------|
+| 基本単位 | オブジェクト | データ + 関数 |
+| 状態管理 | 可変（mutable） | 不変（immutable） |
+| 多態性 | 継承・インターフェース | 判別共用体・パターンマッチング |
+| コード再利用 | 継承 | 関数合成 |
+| 副作用 | どこでも可能 | 境界に分離 |
+
+## 2. OO スタイル → FP スタイル
+
+### Before: OO スタイル（可変状態を持つ）
+
+```fsharp
+/// OO スタイルの銀行口座
+type AccountOO(id: string, initialBalance: decimal) =
+    let mutable balance = initialBalance
+    let mutable transactions: (string * decimal * System.DateTime) list = []
+
+    member _.Id = id
+    member _.Balance = balance
+
+    member _.Deposit(amount: decimal) =
+        if amount > 0m then
+            balance <- balance + amount
+            transactions <- ("deposit", amount, System.DateTime.UtcNow) :: transactions
+            true
+        else false
+
+    member _.Withdraw(amount: decimal) =
+        if amount > 0m && balance >= amount then
+            balance <- balance - amount
+            transactions <- ("withdrawal", amount, System.DateTime.UtcNow) :: transactions
+            true
+        else false
+```
+
+**問題点**:
+- 内部状態が可変
+- テストが困難（状態に依存）
+- 履歴の追跡が難しい
+- 並行処理に弱い
+
+### After: FP スタイル（イミュータブル）
+
+```fsharp
+/// トランザクション
+type Transaction =
+    { Type: TransactionType
+      Amount: decimal
+      Timestamp: System.DateTime }
+
+and TransactionType =
+    | Deposit
+    | Withdrawal
+
+/// 口座（イミュータブル）
+type Account =
+    { Id: string
+      Balance: decimal
+      Transactions: Transaction list }
+
+module Account =
+    /// 口座を作成
+    let create (id: string) (initialBalance: decimal) : Account =
+        { Id = id
+          Balance = initialBalance
+          Transactions = [] }
+
+    /// 入金（新しい口座を返す）
+    let deposit (amount: decimal) (account: Account) : Result<Account, string> =
+        if amount > 0m then
+            let tx = { Type = Deposit; Amount = amount; Timestamp = System.DateTime.UtcNow }
+            Ok { account with
+                    Balance = account.Balance + amount
+                    Transactions = tx :: account.Transactions }
+        else Error "Amount must be positive"
+
+    /// 出金（新しい口座を返す）
+    let withdraw (amount: decimal) (account: Account) : Result<Account, string> =
+        if amount <= 0m then
+            Error "Amount must be positive"
+        elif amount > account.Balance then
+            Error "Insufficient balance"
+        else
+            let tx = { Type = Withdrawal; Amount = amount; Timestamp = System.DateTime.UtcNow }
+            Ok { account with
+                    Balance = account.Balance - amount
+                    Transactions = tx :: account.Transactions }
+```
+
+**改善点**:
+- 状態が不変
+- 元のデータは変更されない
+- Result 型でエラーを表現
+- テストが容易
+- 並行処理に適している
+
+## 3. 継承からコンポジションへ
+
+### Before: 継承ベース
+
+```fsharp
+// OO スタイル（擬似コード）
+// abstract class Animal
+//   def speak(): String
+// class Dog extends Animal
+//   override def speak() = "Woof"
+// class Cat extends Animal
+//   override def speak() = "Meow"
+```
+
+### After: 判別共用体 + パターンマッチング
+
+```fsharp
+type Animal =
+    | Dog of name: string
+    | Cat of name: string
+    | Bird of name: string
+
+let speak (animal: Animal) : string =
+    match animal with
+    | Dog _ -> "Woof"
+    | Cat _ -> "Meow"
+    | Bird _ -> "Tweet"
+
+let getName (animal: Animal) : string =
+    match animal with
+    | Dog name -> name
+    | Cat name -> name
+    | Bird name -> name
+```
+
+**利点**:
+- 新しい動物を追加すると、コンパイラがすべての `match` を更新するよう警告
+- 関数を追加しても既存のコードに影響なし
+- パターンマッチングによる網羅性チェック
+
+## 4. インターフェースから関数レコードへ
+
+### Before: インターフェース
+
+```fsharp
+// OO スタイル
+// interface IRepository<T>
+//   def findById(id: String): Option<T>
+//   def save(entity: T): T
+//   def delete(id: String): Boolean
+```
+
+### After: 関数のレコード
+
+```fsharp
+type Repository<'T> =
+    { FindById: string -> 'T option
+      Save: 'T -> 'T
+      Delete: string -> bool }
+
+/// インメモリリポジトリを作成
+let createInMemoryRepo<'T> (getId: 'T -> string) : Repository<'T> =
+    let mutable data: Map<string, 'T> = Map.empty
+    { FindById = fun id -> Map.tryFind id data
+      Save = fun entity ->
+          let id = getId entity
+          data <- Map.add id entity data
+          entity
+      Delete = fun id ->
+          if Map.containsKey id data then
+              data <- Map.remove id data
+              true
+          else false }
+```
+
+**利点**:
+- テスト用のモックが簡単
+- 部分的な実装が可能
+- 関数を引数として渡せる
+
+## 5. イベントソーシングへの移行
+
+### 従来の可変状態
+
+```fsharp
+// 状態を直接変更
+account.Deposit(100m)
+account.Withdraw(50m)
+// 何が起きたかの履歴は失われる
+```
+
+### イベントソーシング
+
+```fsharp
+/// イベント
+type AccountEvent =
+    | AccountCreated of id: string * initialBalance: decimal
+    | MoneyDeposited of amount: decimal
+    | MoneyWithdrawn of amount: decimal
+
+/// イベントを適用して状態を再構築
+let applyEvent (state: Account) (event: AccountEvent) : Account =
+    match event with
+    | AccountCreated(id, balance) ->
+        { Id = id; Balance = balance; Transactions = [] }
+    | MoneyDeposited amount ->
+        let tx = { Type = Deposit; Amount = amount; Timestamp = System.DateTime.UtcNow }
+        { state with Balance = state.Balance + amount; Transactions = tx :: state.Transactions }
+    | MoneyWithdrawn amount ->
+        let tx = { Type = Withdrawal; Amount = amount; Timestamp = System.DateTime.UtcNow }
+        { state with Balance = state.Balance - amount; Transactions = tx :: state.Transactions }
+
+/// イベントリストから状態を再構築
+let replay (events: AccountEvent list) : Account =
+    let initial = { Id = ""; Balance = 0m; Transactions = [] }
+    List.fold applyEvent initial events
+```
+
+**利点**:
+- 完全な履歴を保持
+- 任意の時点の状態を再構築可能
+- 監査ログとして使用可能
+- デバッグが容易
+
+## 6. 移行戦略
+
+### 段階的アプローチ
+
+1. **新しいコードは FP で書く**
+2. **既存コードの境界に純粋関数を追加**
+3. **可変状態を減らしていく**
+4. **テストを追加しながらリファクタリング**
+
+```plantuml
+@startuml
+title 段階的移行
+
+rectangle "Phase 1" as p1 {
+  card "新規コードを FP で" as new1
+}
+
+rectangle "Phase 2" as p2 {
+  card "境界に純粋関数を追加" as new2
+}
+
+rectangle "Phase 3" as p3 {
+  card "可変状態を削減" as new3
+}
+
+rectangle "Phase 4" as p4 {
+  card "完全な FP 化" as new4
+}
+
+p1 --> p2
+p2 --> p3
+p3 --> p4
+@enduml
+```
+
+## まとめ
+
+本章では、OO から FP への移行について学びました：
+
+1. **可変状態 → 不変データ**: レコード型と `with` キーワード
+2. **継承 → 判別共用体**: パターンマッチングによる多態性
+3. **インターフェース → 関数レコード**: 柔軟な依存性注入
+4. **状態変更 → イベントソーシング**: 完全な履歴保持
+
+## 第7部のまとめ
+
+第7部では、関数型プログラミングの実践的な技術を学びました：
+
+- **パターン間の相互作用**: 複数パターンの組み合わせ
+- **ベストプラクティス**: データ中心設計、副作用の分離
+- **OO から FP への移行**: 段階的なリファクタリング
+
+これらの知識を活用して、保守性が高く、テストしやすい、堅牢なソフトウェアを構築してください。
+
+## 参考コード
+
+本章のコード例は以下のファイルで確認できます：
+
+- ソースコード: `apps/fsharp/part7/src/Library.fs`
+- テストコード: `apps/fsharp/part7/tests/Tests.fs`