データを複製するETLのコードを、値を勝手に変えず、データを外に出さずに作る

## 頼まれない限り、pushやマイグレーションの変更をしない 各変更は、解決対象の問題に集中させる。正しさを保つために広範なリファクタリングが必要な場合を除き、まとまりのある最小差分を優先する。 パターン、依存関係、ヘルパー、テストフィクスチャを導入する前に、周辺のコードを確認し、確立済みのワークスペース規約に従う。フォーマッターの構成、コンパイラーの診断、ワークスペースの静的チェック設定を、強制可能なスタイルの正本として扱う。 ユーザーがその操作を明示的に依頼しない限り、リポジトリへの書き込み、ブランチの公開、変更リクエストの作成、履歴の書き換えを行わない。 依頼された作業でマイグレーション変更が特に必要な場合を除き、データベースマイグレーションを変更しない。マイグレーションファイル内のコメントや実行されないテキストも対象に含む。 高コストなワークスペース全体のチェックは、その範囲に根拠がある場合に限って実行する。リスクの低い文書や構成の変更では、関連する最小限の検証を行い、何を実行したかを正確に報告する。 ## モジュールをデータの中身ごとに分け、APIは最初は非公開にする 汎用的な区分ではなく、ドメインの概念に沿って構成する。レプリケーションの動作とレプリケーション固有の型は同じ場所に置き、再利用可能なデータベースの基本要素、ソース用ヘルパー、スロット用ヘルパー、メタデータへのアクセスは統合境界に置く。 パッケージ境界を設けるのは、別のパッケージがそのAPIへ実際に依存する場合だけとする。1つのドメイン内では、`schema`、`data`、`event`、`store`、`source`、`slots` などの名前を持つモジュールを優先する。 最上位のバイナリーはオーケストレーションに集中させる。実装の詳細は、目的を絞ったヘルパーやモジュールへ移す。 既定では非公開とし、実際の呼び出し元がある場合だけ可視性を広げる。非公開、パッケージスコープ、公開の順で優先する。すべての再エクスポートをAPI契約として扱う。 - 内部モジュールからのワイルドカード再エクスポートを避ける。 - 有用なセットアップ領域のうち最小限だけを公開する。 - ワーカーのオーケストレーション、コーデック、実行時の基盤処理、実装詳細は非公開に保つ。 - 意図的に安定したAPIでない限り、互換性ファサードを避ける。 技巧的な抽象化より、明確で慣例に沿ったコードを優先する。型、コンストラクター、公開メソッド、非公開ヘルパーを読みやすい順序にまとめる。 ## 丸めや切り捨てなど、値が黙って変わるのを防ぐ 丸め、切り捨て、上限または下限への固定、型の強制変換、オーバーフロー、精度低下など、宛先が意味の変化を黙って受け入れてしまう場合は、値をローカルで検証する。 サポートされない値を宛先がすでに明示的なエラーで拒否する場合は、必要性が実証されていない高コストな検証を、書き込み経路で重複して行わない。 損失がなく利用可能な場合は、チェック付きまたはトレイトに基づく数値変換を使う。意図的に損失を伴うキャストを使うのは、その損失を理解し、必要に応じて範囲を確認し、対象の表現に必要な場合だけとする。 暗黙の変換を使うのは、対応関係が失敗せず、意味上の損失がなく、値を保ち、明白な場合だけとする。 パッチ更新では、次の3つの状態を区別してモデル化する。 - 省略されたフィールドは保存済みの値を維持する。 - 明示的なnullは、省略可能な値をクリアするか、既定値を持つ値をリセットする。 - nullではない値は、保存済みの値を置き換える。 完全な構成をパッチの意味へ変換する場合は、明示的な変換ヘルパーを使う。維持からクリアへの変更を、汎用変換トレイトの背後に隠さない。 ## おかしな入力でも落ちずに、分かるエラーを返す 回復可能な失敗には、型付きエラーと結果値を使う。元のエラーを原因チェーンとして保ちながら、操作、識別子、件数、型、ステートメントなどの所有されたコンテキストを加える。 意図的に無害化したメッセージの方が呼び出し元にとって安全な場合を除き、下位のエラーを文字列へ平坦化しない。公開APIの応答で、データベースドライバーのエラー、内部クエリ、顧客データ、インフラストラクチャの詳細を明かしてはならない。 パニックは、プログラマーが守るべき不変条件が破られた場合に限る。外部入力、不正な構文、サポートされない値、システム状態の失敗では、明示的なエラーを返さなければならない。 パーサーの入口は、空の入力、予期しない入力終端、不正なエスケープ、無効なバイト列、無効な範囲、オーバーフロー、アンダーフロー、サポートされない構文を、パニックせずに処理しなければならない。 入力がオフセットを制御する場合は、チェック付きアクセス、イテレーター、バイトスライスの解析を優先する。直接インデックスを使ってよいのは、ローカルな境界条件または正確なチャンクの不変条件によって安全性が明白な場合だけとする。 以前はパニックや暗黙の誤解析を起こし得た、不正入力の境界すべてに回帰テストを追加する。 ## 裏で動くタスクの止め方を、持っている状態に合わせて選ぶ 必要な場合を除き、unsafeコードを避ける。すべてのunsafeブロックには、その操作が健全であることを支える不変条件を述べた安全性の説明を隣接させなければならない。 不要なクローンや内部可変性より、所有権と借用を優先する。 長時間動作する非同期処理は、名前を付けたタスクまたはヘルパーの背後に置き、所有する状態に応じてシャットダウン動作を選ぶ。 - タスクハンドルをドロップすると、タスクは切り離される。直ちに停止すべき破棄可能なバックグラウンド処理は、明示的に中止する。 - タスクセットをドロップすると、そのセットが所有するすべてのタスクが中止される。 - タスクセットがドロップされるスコープを抜ける直前に、同じタスクセットを重複して中止しない。 - タスクセット自体は存続するが、そのタスクを停止する必要がある場合は、明示的な中止操作を使う。 - タスクがトランザクション、バッファー済みの宛先書き込み、または再試行の影響を受けやすいレプリケーション状態を所有する場合は、正常終了シグナルとjoinを使う。 状態を安全に破棄できるポーリングやテレメトリのタスクに、複雑なシャットダウン調整を追加しない。 ## 秘密情報とお客さんのデータを、コードやログに入れない 追跡対象のファイル、ブランチ、コミット、レビュー、ログ、スクリーンショット、フィクスチャ、生成物、端末出力は、外部から見られる可能性があるものとして扱う。 認証情報、トークン、内部専用エンドポイント、顧客データ、本番ペイロード、個人データ、専有構成を、コード、テスト、文書、例、コメント、メッセージ、テレメトリ、パニックの詳細、生成ファイルに決して含めない。 例では架空のプレースホルダーを使う。実際の秘密情報は、承認済みの環境変数、追跡対象外のローカルファイル、シークレット管理システム、CIのシークレット保管領域だけに保存する。 疑わしい値が本物に見える場合、または非公開環境から得た場合は、その値を再掲しない。公開工程を停止し、値を引用せずに場所を報告し、漏えいした可能性がある場合はローテーションまたは無効化を推奨する。 可観測性については、次を守る。 - カーディナリティの低いラベルを優先する。 - テーブル名、列名、型、件数、長さ、位置、操作名などの構造メタデータをログに記録する。 - 行の値、セルの内容、機密性の高い要求または応答の本文、認証情報、トークンを決してログに記録しない。 - エラーと構造化フィールドには、安全な表示形式を使う。 - 機密性の高い経路と監視範囲では、本文の取得内容から機密情報を除去する。 ## 複製のイベントを実際にテストし、テストが本当に動いたか確かめる 最も狭い範囲の関連テストから実行し、共有動作、回帰、または依頼に根拠がある場合に範囲を広げる。期待したテストが実際に実行されたことを確認する。一致するテストが0件のままコマンドが成功しても、検証合格とはみなさない。 不確かなフィルターを適用する前に、テストを一覧表示する。主要なテスト実行系が文書テストに対応していない場合は、文書テストを別に実行する。 独自のテスト用接続処理を作る前に、周辺にあるフィクスチャ、データベース用ヘルパー、待機プリミティブ、アサーションを再利用する。 イベント駆動型の統合テストでは、次の順序を守る。 1. 生成側がイベントを発行できるようになる前に、通知または待機ハンドルを登録する。 2. ソース側で書き込みを行う。 3. 期待する通知を待つ。 4. 実行中の動作をテストが明示的に対象とする場合を除き、宛先の状態をアサートする前にパイプラインを停止し、終了を待つ。 5. 再起動または分離された段階で履歴をクリアする必要がある場合を除き、累積イベント履歴に対してアサートする。 期待する変更データキャプチャイベントを、ソースデータベースの実際のレプリカアイデンティティ動作に合わせる。部分更新行を生成できないモードで、その行を期待してはならない。 ## コードに説明を書き、実行した確認を報告する 公開項目と非公開項目を、簡潔で正確な文章で文書化する。文書システムが対応する参照方法で型とメソッドをリンクする。コメントには句読点を付け、説明対象のコードより上に置く。 メトリクス名とラベルキーを定数として定義し、共有ラベルを一元管理し、説明を一度だけ登録する。ソースごとに目的を絞ったメトリクスタスクを1つ置き、オーケストレーション領域は小さく保つ。 完了前に、影響範囲について次を確認する。 - 変更対象がコンパイルできる。 - フォーマットが合格する。 - ワークスペースの静的チェック構成を使った静的解析が合格する。 - 関連する単体テストと統合テストが合格し、実際に実行されている。 - 該当する場合は文書テストが合格する。 - コメントと文書が最終的な動作と一致する。 - メトリクス、ログ、ラベルが命名規則とデータ安全規則に従う。 実行したチェック、その範囲、意図的に省略したチェックを報告する。コマンドの出力から有意な対象が実行されていないと分かる場合は、終了状態だけを根拠に完了を主張しない。