Site icon imageTomoMemo.dev

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

郵便番号取得APIを作りたい（vol.1）

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

  • 郵便番号・デジタルアドレスAPIが公式でリリースされている
    • こちらを使えば事足りるが、郵便番号を取得する仕組みが作れるAPIを元々作ってみたかったのでやる。
  • Dynamo DBの設計・実装・構築もできるようになりたい（というのも目的の1つ）

プロジェクト概要

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

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

ETL: Extract（抽出）・Transform（変換）・Load（ロード）の略

異なるシステムからデータを抽出し、変換・加工して、データウェアハウス等分析基盤に格納する一連のプロセス（らしい！）

何を作るか

  • 郵便番号取得API
    • 学習目的で「郵便番号→住所(複数候補)」のシンプルAPIをゼロから構築
    • DynamoDB設計／AWS CDK／サーバレス運用を通しで練習
      • DynamoDBの設計, 構築, 運用できるようになりたい
    • 公式の日本郵便API(2025/5公開)は既に無料&最新反映だが、Tech Drivenに自作する
項目決定（MVP）補足・拡張余地
対応APIGET /v1/zip/{code} 郵便番号→住所(複数候補)取得逆引き・あいまい検索は後続バージョンで追加（仮）
データソース日本郵便公開CSV（KEN_ALL系）を月1取込し内部DBを更新公式API直叩きモードは後で比較学習用に実装可。 CSVは継続提供・月次更新。 (郵便局 | 日本郵便株式会社, ZipCloud)
データ格納DynamoDB（オンデマンド）単一テーブル、PK=zip(郵便番号), SK=デジタルアドレスid(addrId)で1:Nができそう将来逆引き用にGSI(Global Secondary Index)追加可。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

現状の解像度が低いところ
  • Notion Slideの仕様上表示されないので省略！
  • 結構多いので要調査！
論点現在の状態最低限ここまで決めれば開発開始できる決めるための情報ソース・ヒント
公式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段（今回はdev環境のみ,）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)

インフラ構成

  • 使用言語
    • AWSリソース構築はTypeScript
    • 各AWSリソースへの関数実装はPython
  • 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)

データソース & 更新

開発フロー

フェーズ一覧（実施順）

  • 環境構築
  • CSV仕様把握
  • Dynamoスキーマ決定
  • Lookup Lambda + API GW
  • 月次IngestジョブNext.js入力フォーム/JSONビュー（+α 公式APIの仕様調査）
  • インセプションデッキの考え方を土台に開発を実施

フェーズゴール成果物補足
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仕様

  • 郵便番号の入力・エンドポイント・json形式で住所情報の取得が確認できる状態を想定
ユースケース
  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ストリーム → Batchで書き込み? (Upsert?)
  • CSVは公式KEN_ALLフォーマット（郵便番号-住所対応／zip圧縮／可変長CSV）。公開サイトは月次で更新（zipcloudでも最新更新日が確認可）。 (郵便局 | 日本郵便株式会社, ZipCloud)

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

DynamoDB設計の観点

  • アクセスパターン駆動設計
    • 「どんなクエリを投げるか」からDynamoDBのテーブル設計を逆算する手法
      • どんなデータを「どう取得・更新したいか」（アクセスパターン）を最初に洗い出す
      • そのパターンに合わせてテーブル構造・キー・インデックスを設計
      • RDBの正規化発想ではなく「使い方」から逆算するのがDynamoDB流（らしい）
    • まず郵便番号既知→候補取得に最適化
    • 将来アクセスパターン追加時はGSI追加で拡張（逆引き・検索）/ やるかは一旦保留
  • 均等なパーティション分布とホットパーティション回避に注意
    • 郵便番号は十分分散するが、局所的ホットを避けるシャーディング戦略も検討
    • AWS公式ベストプラクティス参照 (AWS Documentation, AWS Documentation)

AIの使い方

  • GPT-5
    • 要件定義／スキーマ草案／CDK雛形生成／テストケース列挙／公式APIとのフィールド差分抽出を実施予定
    • 公式API機能（最新反映・ローマ字・フリーワード）の調査／ユースケースまとめ
  • Claude Code
    • 要件定義以降の工程で使用
    • subagentを構築
      • awsリソース構築用
      • 各リソースの
      • フロントエンド

Back-EndAWSAPI
Powered by Tomo with passion.