Site icon imageTomoMemo.dev

Memo on programming for Junior SWE. Provided by Tomo with passion.
2025-07-12
Back-EndAWSAPI

郵便番号取得APIを作りたい

郵便番号・デジタルアドレスAPIが公式でリリースされているので、こちらを使えば事足りるが、郵便番号を取得する仕組みが作れるAPIを元々作ってみたかったのでやる。

Dynamo DBの設計もできるようになりたい、というのも目的の1つ。

プロジェクト概要

「DynamoDB設計」「AWS CDKによるIaC」「月次CSV取込」「Next.js UI（Vercel）」までを一気通貫で練習する小規模サーバレスプロジェクト。

公式の 日本郵便「郵便番号・デジタルアドレスAPI」 が2025/5公開され、無料かつ最新データを返せる時代になったが、あえて自作することでデータモデル／ETL／API設計／クラウド環境構築の実戦力を鍛えることが目的。

何を作るか

項目決定（MVP）補足・拡張余地
対応APIGET /v1/zip/{code} 郵便番号→住所(複数候補)取得逆引き・あいまい検索は後続バージョンで追加（仮）
データソース日本郵便公開CSV（KEN_ALL系）を月1取込し内部DBを更新公式API直叩きモードは後で比較学習用に実装可。 CSVは継続提供・月次更新。 (郵便局 | 日本郵便株式会社, ZipCloud)
データ格納DynamoDB（オンデマンド）単一テーブル、PK=zip, SK=addrIdで1:N将来逆引き用にGSI追加可。Partition設計ベストプラクティスに従う。 (AWS Documentation, AWS Documentation)
フロントNext.jsフォームで7桁入力→候補リスト＆JSONビューVercel環境変数でAPIエンドポイント注入。 (Vercel, Next.js)
IaC/インフラAWS CDK(TypeScriptの予定)
Lambda, API GW, DynamoDB,
EventBridge, S3		AWS Documentation, AWS Documentation

現状の解像度が低いところ
論点現在の状態最低限ここまで決めれば開発開始できる決めるための情報ソース・ヒント
公式APIとの比較観点「知らないので不明」公式APIが返すフィールド一覧とレスポンス遅延目安をざっくり把握（数リクエスト叩いて計測）日本郵便APIは最新データをタイムリー反映・漢字/カナ/ローマ字返却・フリーワード検索対応。これを“できない/しない理由”を学習ゴールに明示。 (郵便番号・デジタルアドレス for Biz, 郵便番号・デジタルアドレスAPI｜日本郵便株式会社)
データ更新ジョブ時刻月1でやる（具体日未定）毎月1日 03:00 JST or EventBridge cron(0 18 L * ? *)など「月末/翌月頭」どちらか固定日本郵便CSVは継続提供・月次更新（KEN_ALL）。zipcloudも月次で最新ファイル公開。 (郵便局 | 日本郵便株式会社, ZipCloud)
スキーマ詳細PK=zip想定／1:N考慮addrId生成方式（hash or composite text）と必須属性（pref/city/town）を決めるDynamoDBはアクセスパターン先行設計＆ホットパーティション回避が推奨。 (AWS Documentation, AWS Documentation)
環境分離dev/prd 2段CDKコンテキスト -c stage= で環境名を注入するか、スタック名suffix方式か決めるCDKでLambda+API Gateway+DBを一括デプロイする公式チュートリアルを参照。 (AWS Documentation, AWS Documentation)
フロントのホスティングVercel（おそらくこれにする）dev=Preview, prd=ProductionでAPI URLを環境変数注入Vercel環境変数ガイド／Next.js環境変数ガイド参照。 (Vercel, Next.js)

技術スタック

フロントエンド

  • Next.js 14 + TypeScript（App Router）
  • 状態: TanStack Queryでフェッチキャッシュ管理
  • JSON表示: react-json-view
  • デプロイ: Vercel（GitHub連携／Previewブランチ／環境変数でAPI差替）。Vercelは環境ごとに暗号化されたEnv Varを設定できる（NEXT_PUBLIC_ ）prefixでクライアント公開可能できる見込み。 (Vercel, Next.js)

バックエンド

  • AWS Lambda (Node.js LTS)
  • Amazon API Gateway (REST)
  • Amazon DynamoDB（オンデマンド課金）

IaCは AWS CDK v2 (TypeScript)。

DynamoDBキー設計はアクセスパターン（郵便番号既知→候補一覧）に最適化、ホットパーティション回避・将来のGSI拡張を考慮する設計ベストプラクティスに従う。 (AWS Documentation, AWS Documentation)

データソース & 更新

インフラ構成

  • S3（CSV格納）
  • EventBridge (月次cron) → Ingest Lambda（CSV→Dynamoアップサート）
  • Lookup Lambda（/v1/zip/{code}）
  • API Gateway（API Key or IAM, 社内利用）
  • CloudWatch Logs / Metrics
  • すべてCDKで定義（ステージごとにスタック分離）。公式CDKチュートリアルのLambda+API+他サービス統合パターンを応用できそう。 (AWS Documentation, AWS Documentation)

開発フロー

フェーズ一覧（実施順）

フェーズゴール成果物補足
0 準備（AWSアカウントを新規作成）リポ初期化、CDK bootstrap、Vercelプロジェクト作成、dev/prd環境の構築repo skeleton / dev credentialsCDK公式手順を参考 / bootstrap & sample Lambda。 (AWS Documentation, AWS Documentation)
1 データ理解日本郵便CSVフォーマット解析、必要列抽出スキーマメモ / サンプル行CSV仕様（KEN_ALLなど）公式説明参照。 (郵便局 | 日本郵便株式会社, ZipCloud)
2 スキーマ決定PK=zip / SK=addrId / 属性セットDynamoDBテーブルキー設計ベストプラに沿う。 (AWS Documentation, AWS Documentation)
3 Lookup APIGET /v1/zip/{code} 実装 & 単体テストLambda + API GWCDK + Lambda + API GW例に基づく。 (AWS Documentation, AWS Documentation)
4 Ingest Job月次CSV取込Lambda + EventBridge郵便番号更新自動化CSV→Dynamoパイプライン。 (郵便局 | 日本郵便株式会社, ZipCloud)
5 フロントUI郵便番号入力→候補表示＋JSONビューVercelデプロイEnv VarでAPI差替。 (Vercel, Next.js)
+α 公式API比較自作API vs 日本郵便公式APIの精度/遅延比較ベンチ結果 & メモ公式APIは最新反映・ローマ字返却・フリーワード対応。 (郵便番号・デジタルアドレス for Biz, 郵便番号・デジタルアドレスAPI｜日本郵便株式会社)

フロントUI仕様

ユースケース
  1. ユーザーが7桁郵便番号を入力（未満時は無効）
  2. デバウンス後APIコール
  3. 返却配列をリスト表示（都道府県＋市区町村＋町域）
  4. 「JSONを表示」トグルで生データ（1:N構造）を確認
  5. （オプション）コピー用ボタン
    1. 余裕あればやる
環境切替

NEXT_PUBLIC_API に dev/prd API Gateway URL を設定（Vercel環境変数UIから登録、Next.jsではNEXT_PUBLIC_付でクライアント利用可）。 (Vercel, Next.js)

データ更新（ETL）仕様メモ

  • トリガ: 月1（cron）で日本郵便公開CSVダウンロード
  • 処理: zip解凍 → CSVストリーム → BatchWrite (Upsert)
  • CSVは公式KEN_ALLフォーマット（郵便番号-住所対応／zip圧縮／可変長CSV）。公開サイトは月次で更新（zipcloudでも最新更新日が確認可）。 (郵便局 | 日本郵便株式会社, ZipCloud)

なお、公式APIは「マスタ更新にあわせてタイムリー反映」「ローマ字返却」「フリーワード検索」等を提供しているらしい。

DynamoDB設計の観点

  • アクセスパターン駆動設計
    • まず郵便番号既知→候補取得に最適化
    • 将来アクセスパターン追加時はGSI追加で拡張（逆引き・検索）/ やるかは一旦保留
  • 均等なパーティション分布とホットパーティション回避に注意
    • 郵便番号は十分分散するが、局所的ホットを避けるシャーディング戦略も検討
    • AWS公式ベストプラクティス参照 (AWS Documentation, AWS Documentation)

Back-EndAWSAPI
Powered by Tomo with passion.