QUARTETCOM TECH BLOG

Symfonyの.envファイルをうっかり git プッシュから守る方法 | QUARTETCOM TECH BLOG

Mon, 16 Mar 2026 00:00:00 +0900

Symfony でアプリ開発をしていると .env.local にクレデンシャルをハードコードすることがありますが、センシティブな情報をプレーンテキストで扱うことに若干の怖さを感じています。かんたんにリネームもファイルコピーもできますし GitHub リポジトリに間違えてプッシュしちゃったら怖いですよね。

そんなうっかり操作のヒヤリハットを何らかの仕組みで防止できないか調べてみました。

はじめに

この記事の「クレデンシャル」とは Symfony アプリ内でクローズドに利用する接続情報やトークンのことを示しています。パラメータを経由してサービスクラスに注入しサードパーティベンダーの認証などに使用するイメージです。

# .env.local
APY_KEY=1234abcd
SLACK_TOKEN=xoxb-000000000000-EXAMPLE-TOKEN

# config/services.yaml
parameters:
    apiKey: '%env(APY_KEY)%'
    slackToken: '%env(SLACK_TOKEN)%'

App\Command\SomeService:
    arguments:
        $apiKey: '%apiKey%'
        $slackToken: '%slackToken%'

クレデンシャルは API キー / OAuth 認証トークン / デベロッパートークンなどさまざまな種類があり、ハードコード先も .env.* だけでなく .key .yaml などバリエーションがあります。広範囲に散らばっているクレデンシャルを守るには、いくつかの方法を組み合わせて多層防御するのがベターと言えそうです。

.env.local を git で追跡しない：.gitignore

gitignore は基本的でシンプルな方法です。.gitignore に書いたパターンにマッチすると git で追跡されず、ステージもコミットもされません。Symfony CLI でプロジェクトを作成するとプロジェクトに最適な .gitignore が作成されます。

# .gitignore

###> symfony/framework-bundle ###
/.env.local
/.env.local.php
/.env.*.local
...

けれどもプロジェクトは常に Symfony CLI で構築されるとは限りません。別プロジェクトからソースコードを流用したり、ゼロベースからディレクトリを構成することもあるでしょう。

https://github.com/github/gitignore のようなテンプレートを使って .gitignore を作成した場合 .env.* はその対象に含まれていないかもしれません。記事執筆時点の Symfony 最新バージョンは v8.0.6 ですがテンプレートは v4 以降のリリースに追随していないように見えます。

gitignore /Symfony.gitignore

グローバル設定の ~/.config/git/ignore に .env.* と書いてあるから安全！という思い込みもうっかりミスを誘発します。新しいデバイスをセットアップした時、このディレクトリの同期作業をうっかり忘れてしまうかもしれないからです。

.gitignore による追跡防止は 開発の基本であって過信しないこと というのが私の考えです。

.env.local をコミットしない：1Password Local .env files

1Password は有償のパスワードマネージャーです。
2025/10 に「Local .env files」というベータ版機能がリリースされました。この機能は .env ファイルを安全な場所に退避し、プロセスからの読み取りに開発者の許可を必要とします。

Introducing new .env file support in 1Password environments | 1Password

1Password アプリで「環境」を追加しプロジェクトを判別する任意の名前を付与します。

追加した環境に .env.local をインポートします。

プロジェクトの既存の .env.local を削除し、替わりに 1Password のファイルを保存（マウント）します。

マウントした .env.local はファイルの実体ではなく UNIX の名前付きパイプです。その内容は 1Password によって保護されているため、プロセスが読み取ろうとすると認証ダイアログが表示されます。許可すると 1Password アプリのロックがかかるまでアクセスが可能になります。

この仕組みは「うっかりプッシュ」の観点で良い副作用をもたらします。ファイルの実体ではないため git でコミットできない のです。.gitignore にうっかり書き忘れても、.env.locall とファイル名をタイポしても、コミット時点でブロックされます。

git add .env.local
> error: .env.local: can only add regular files, symbolic links or git-directories
> fatal: updating files failed

そして .env.local を一元管理できるメリットもあります。自宅とオフィスで PC を使い分けているような場合、どのデバイスでも 1Password からマウントしておけば「自宅の PC で変更した内容をオフィスの PC に反映し忘れた」なんてことがなくなります。

ただし落とし穴もあります。一時的なバックアップのために cp .env.local .env.local.bak を実行すると .env.local.bak はファイルの実体として作成され、うっかりコミットが可能になります。

.env.local を作らない：Symfony’s secrets management system

そもそもクレデンシャルを .env.local にハードコードしない手段についても検討の余地があります。Symfony 公式で紹介されている「Symfony’s secrets management system」はそのひとつです。

How to Keep Sensitive Information Secret | Symfony docs

この方法は PHP 7.2+ でバンドルされているモジュール sodium を使ってクレデンシャルを暗号化し config/secrets/* に格納します。

# モジュールが含まれているか調べる
php -m | grep sodium
> sodium

クレデンシャルの登録や削除はコマンドで行います。

# 暗号化・復号化のためのキーペアを作成（初回のみ）
php bin/console secrets:generate-keys

# クレデンシャルを登録
php bin/console secrets:set API_KEY

プロダクション環境用にはプレフィクス APP_RUNTIME_ENV=prod を付与してコマンドを実行します。

# 暗号化・復号化のためのキーペアを作成（初回のみ）
APP_RUNTIME_ENV=prod php bin/console secrets:generate-keys

# クレデンシャルを登録
APP_RUNTIME_ENV=prod php bin/console secrets:set API_KEY

一部のクレデンシャルをローカル開発用にカスタマイズする時は --local オプションを使用します。

bin/console secrets:set API_KEY --local

dev prod local それぞれの環境用に生成されたファイル群は以下のように格納されます。

config/secrets
├── dev
│   ├── dev.API_KEY.b58958.php # 個別のクレデンシャル
│   ├── dev.decrypt.private.php # 復号化の秘密鍵
│   ├── dev.encrypt.public.php # 暗号化の公開鍵
│   ├── dev.list.php # クレデンシャルのリスト
└── prod
    ├── prod.API_KEY.b58958.php # 個別のクレデンシャル
    ├── prod.decrypt.private.php # 復号化の秘密鍵
    ├── prod.encrypt.public.php # 暗号化の公開鍵
    └── prod.list.php # クレデンシャルのリスト

.env.dev.local # ローカル開発用にカスタマイズした値

これらのファイルのうち、プロダクション環境の秘密鍵 prod.decrypt.private.php だけはコミットしてはいけません。秘密鍵を直接サーバーに置くか、サーバーの環境変数 SYMFONY_DECRYPTION_SECRET に登録します。

# (A) サーバーに直接配置
config/secrets/prod/prod.decrypt.private.php

# (B) 環境変数に登録
export SYMFONY_DECRYPTION_SECRET={Base64 エンコードした鍵}

登録したクレデンシャルはコマンドでリストアップできます。

# --reveal オプションで値の表示ができる
php bin/console secrets:list --reveal

> ------------ ---------- ------------- 
>  Secret       Value      Local Value  
> ------------ ---------- ------------- 
>  API_KEY      "123abc"   "111aaa"    
>  DB_PASSWORD  "123def"   "222bbb"
> ------------ ---------- ------------- 

この仕組みは .env.* を使用せず 「うっかりプッシュ」対象を「プッシュしても良い情報」 に置き換えます。ただしローカル開発用にカスタマイズした .env.dev.local は依然としてうっかりコミットの可能性が残ります。

プッシュをブロック：GitHub Push protection

クレデンシャルの格納先は .env.* とは限りません。.key .yaml にハードコードした内容を無害なファイルパスとして .env.local に渡すことがあります。GitHub の Push protection はそのようなケースで有効です。

ユーザーのプッシュ保護 | GitHub ドキュメント

Organization に属さない個人アカウント配下でパブリックなリポジトリを作成したところ、デフォルトで Push protection が有効になっていました。

試しに AWS アカウントなどダミーのクレデンシャルを書いたファイルをプッシュすると Push protection によってデータ転送がブロックされました。

# config/keys/sample.key

DUMMY_GITHUB_TOKEN=ghp_dummy12341234nopqrstuvwxyz....
DUMMY_AWS_KEY=AKIAQA2IFJE3MPUDUMMY
DUMMY_AWS_SECRET=gsDummyyGtzLXigRMVcDHeuS7Neg6vd....

# 主要な部分のみ抜粋
git push origin main

Enumerating objects: 8, done.
Counting objects: 100% (8/8), done.
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
remote: error: GH013: Repository rule violations found for refs/heads/main.
remote: 
remote: - GITHUB PUSH PROTECTION
remote:   —————————————————————————————————————————
remote:     Resolve the following violations before pushing again
remote:     - Push cannot contain secrets
remote:     
remote:       —— Amazon AWS Access Key ID ——————————————————————————
remote:        locations:
remote:          - commit: 0a000111222...
remote:            path: config/keys/sample.key:4
remote:     
remote:       —— Amazon AWS Secret Access Key ——————————————————————
remote:        locations:
remote:          - commit: 0a000111222...
remote:            path: config/keys/sample.key:5
remote: 
 ! [remote rejected] main -> main (push declined due to repository rule violations)

# ブロックしてくれた ☺️

ダミーの RSA 秘密鍵も試したところ、こちらは Push protection が反応せずプッシュが完了しました。

# config/keys/sample.key（実在しないクレデンシャル）

-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEArandomrandomrandomrandomrandomrandomrandomrandom
....
-----END RSA PRIVATE KEY-----

git push origin main
> Total 0 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
> + 1234c7c...4567ccc main -> main

# プッシュ完了...🙄

GitHub ドキュメントの Supported secrets を読むと Push protection は単純なパターンマッチングのようなチェックではないことが分かります。

トークン提供元のプロバイダ（AWS / Google など）によるチェックと、非プロバイダ（Generic）に分かれる
プロバイダにクレデンシャルを送信してトークンの有効性をチェックすることがある
トークンやプロバイダによってチェック内容の網羅度合いが異なる
個人アカウントのパブリックリポジトリに適用されるチェックと GitHub Team / Enterprise の GitHub Secret Protection で適用されるチェックに違いがある

偽物のクレデンシャルとほんの数回のプッシュ確認では、ブロック可能なパターンを帰納的に洗い出すことはできませんでした。

しかしながら、あらゆるクレデンシャルを対象に GitHub がスキャンしてくれる機能はとても強力です。ブロックが成功した AWS アクセスキーについてはファイルから削除するだけではダメで、コミットログも完全に消し去らないとプッシュができませんでした。

GitHub Push protection は .env.local の 外に漏れ出てしまった情報の監視役 として有効に機能してくれそうです。

まとめ

Symfony や GitHub など、それぞれがうっかりプッシュの防止策を提供してくれています。どれもすべてのクレデンシャルやユースケースを網羅できる仕組みではありませんが、組み合わせれば高い効果が期待できそうです。

これさえやっておけば大丈夫！と慢心せず、ローカルでもクラウドでも電子的に保存したデータは常に漏洩リスクを孕んでいることを念頭に開発していきたいと思っています。

Claude Code 入門: 導入から基本操作・コスト管理まで | QUARTETCOM TECH BLOG

Tue, 24 Feb 2026 00:00:00 +0900

開発部では最近、開発効率を向上させる施策の一環として、Anthropic 社の CLI 型 AI エージェント「Claude Code」を導入しました。

本記事は、これから Claude Code を触ってみたいエンジニアや、AI ツールによる開発効率化に関心のある方に向けた実践ガイドです。

今回は、「基本概念」から、コストを抑える運用まで共有します。

1. まず押さえたい基本概念: 「セッション」と「コンテキスト」

Claude Code を使いこなす上で、以下の 2 つの概念を理解しておくとスムーズです。

セッション（作業のまとまり）

Claude Code は、起動してから終了するまでの一連のやり取りを「セッション」として管理します。

最も重要な仕様は、セッションは「起動ディレクトリ（フォルダ）」に紐付いて管理されるという点です。

[プロジェクトAのディレクトリ] ⇔ [セッションA（Aの記憶）]
        ｜
    (ディレクトリ移動)
        ↓
[プロジェクトBのディレクトリ] ⇔ [セッションB（Bの記憶）]

つまり、ディレクトリを移動して新しく claude を起動すれば、別のセッションとして扱われます（前のディレクトリのコンテキストを引きずりません）。

履歴は保存されているため、完全に消失するわけではありません。

後述の /resume コマンドを使えば、過去のセッション一覧から再開したい作業を選んで元の状態を復元できます。

コンテキスト（AI の短期記憶）

AI が一度に覚えられる情報量のことです。会話が長くなると、この「コンテキスト」が溜まっていきます。

コンテキストが溜まると、AI が処理すべき情報量が増えるため、結果として利用料（コスト）も上がってしまいます。

2. 初期設定: `/init` と `CLAUDE.md`

プロジェクトの「記憶」を作る `/init`

初めて Claude Code を使うディレクトリでは、最初に以下のコマンドを実行します。

> /init

これを実行すると CLAUDE.md というファイルが生成されます。ここにはビルドコマンドやコーディング規約などを記述します。 Claude Code は起動時にこのファイルを読み込み、プロジェクトのルールを理解します。

チーム開発での運用ルール

共有設定（Git 管理する）: プロジェクトルートの CLAUDE.md はGit にコミットします。これにより、チーム全員が同じルール（ビルド手順や規約）を共有でき、通常は他のメンバーが /init を実行する必要がなくなります（既に設定ファイルが存在するため）。

要件定義ファイルなどの扱い

CLAUDE.md はあくまで「ルールブック」です。機能ごとの仕様書などは docs/spec.md などのファイルに分け、指示出しの際に @docs/spec.md のように参照させます。

3. うまく伝わらない時は？コンテキスト管理のコツ

使っていると、「最近、指示の意図を汲んでくれなくなったな……」と感じることがあります。これはコンテキストが溜まりすぎて、AI が混乱しているサインかもしれません。

基本は `/clear` でリセット

タスクの区切りや、話が噛み合わなくなったら、以下のコマンドを打ちます。

> /clear

これにより、これまでのコンテキストが消去され、まっさらな状態で再スタートできます。 CLAUDE.md の内容は保持されます。

コンテキストを残したいなら `/compact`

「今の文脈は維持したいけど、少し記憶を整理したい」という場合は /compact が有効です。

これは会話の要約のみを残し、個別のやり取りの詳細な履歴を削除することで、コンテキストを圧縮します。

4. 利用状況の確認とモデルの使い分け

Claude Code の利用状況や制限は、以下のコマンドで確認できます。契約形態（サブスクリプションまたは API 課金）によって使い分けます。

利用状況の確認

サブスクリプションプランの場合: /usage コマンド
- Claude Pro などのサブスクリプションプランで利用している場合、ここからレートリミット（残り使用回数）やプランの使用状況を確認できます。
API キーを利用（従量課金）の場合: /cost コマンド
- 組織で API キーを利用（従量課金）している場合、現在のセッション費用を確認できます。

モデルの使い分け

Sonnet 系モデル: 日常的なコーディングや修正。速度とコストのバランス型です。
Opus 系モデル: 複雑な設計や難解なバグ調査。高精度で、深い推論を必要とする作業向けです。

※モデル性能はアップデートにより変更される場合があります。

5. 急な割り込み対応（セッション管理）

開発中に緊急対応が入った場合も、セッション機能を使えば安全に中断・再開できます。

中断: 作業中のセッションに /rename [タスク名] で名前を付けて保存します。
再開: /resume で過去のセッションを選択し、元の状態（コンテキスト含む）から再開できます。
並行作業: Claude Code のセッションはディレクトリに紐付いています。そのため、git worktree でディレクトリを分け、セッションを分離して並行作業できます。片方で「バグ調査」をさせつつ、もう片方で「新機能実装」を進めるなど、互いのコンテキストを混ぜずに並行作業が行えます。

まとめ

基本: セッションはディレクトリに紐付くため、場所を変えて起動すれば記憶も変わる。
設定: チームルールはルートの CLAUDE.md（Git 管理）
維持: 話が噛み合わなくなったら /clear。コスト節約にもなる。
運用: モデルの使い分けと /resume で柔軟に対応。

ぜひ、皆さんの開発フローにも取り入れてみてください。

GitHubのマージ（Merge Commit/Squash Merging/Rebase Merging）の違い | QUARTETCOM TECH BLOG

Fri, 05 Dec 2025 00:00:00 +0900

GitHub でプルリクエストをマージする時、マージボタンのプルダウンに「Squash and merge」「Rebase and merge」ってありますよね。これらの違いをよく知らなかったので手元で試してみました。

プルリクエストのマージについて | GitHub ドキュメント

動作確認用に使ったプルリクエストはタイトルを PR-A に、コミットメッセージを A1 {コミット時刻} と統一しています。

1) Create a merge commit

プルダウンを展開せずにマージボタンを押したデフォルトの動作です。

同じブランチから切った複数ブランチをマージすると、時系列でコミットが積み上がります。

メインブランチに見立てた merge にブランチ merge-A merge-B をマージすると次の図のようになります。

git log merge-A
> 44b8478 A2 21:25
> fba0ad2 A1 21:23

git log merge-B
> 6bfb8c4 B2 21:26
> 74b8961 B1 21:24

git log merge
> 881e805 Merge pull request #18 from ringtail003/merge-B
> d2bef64 Merge pull request #17 from ringtail003/merge-A
> 6bfb8c4 B2 21:26 <== プルリクエスト(2)のコミット
> 44b8478 A2 21:25 <== プルリクエスト(1)のコミット
> 74b8961 B1 21:24 <== プルリクエスト(2)のコミット
> fba0ad2 A1 21:23 <== プルリクエスト(1)のコミット

GitHub でサンプルを見る

2) Squash and merge

Squash はプルリクエストのコミット群をひとつにまとめた新しいコミットを作成します。マージ先のブランチでは、プルリクエストとコミットが 1 対 1 になります。

メインブランチに見立てた squash にブランチ squash-A squash-B をマージすると次の図のようになります。

git log squash-A
> 36001a5 A2 21:33 <== マージ元のコミット(2個目)
> 709eb44 A1 21:30 <== マージ元のコミット(1個目)

git log squash-B
> 2d087cb B2 21:34
> aea1a38 B1 21:32

git log squash
> 7d65cc7 PR-B (#20)
> 6d63afc PR-A (#19) <== マージ先のコミット（1個にまとまる）

GitHub でサンプルを見る

Squash and merge の Author

いくつかプルリクエストを作って試したところ、プルリクエストに一番最初にコミットした人がマージコミットの Author として採用されるようです。

プルリクエストに 2 番目以降にコミットした人は「共作者」という扱いになります。

git log --pretty=full

> commit 1234abc
> Author: user1 <user1@example.com>
> Commit: GitHub <noreply@github.com>
>  PR-A (#100)
> 
>  * A1
>  * A2
>  ---------
>  Co-authored-by: user2 <user2@example.com> <== 共作者

複数の作者を持つコミットを作成する | GitHub ドキュメント

3) Rebase and merge

Rebase はプルリクエストをマージ先ブランチでリベースしてからコミットを積みます。そのためコミットにそれぞれ新しいハッシュが付与されます。

メインブランチに見立てた rebase にブランチ rebase-A rebase-B をマージすると次の図のようになります。

git log rebase-A
> 7258210 A2 21:39
> 7fcedd0 A1 21:37 <== マージ元のコミット

git log rebase-B
> 6ecf78f B2 21:40
> 5bd574d B1 21:38

git log rebase
> 3acd2d8 B2 21:40
> f4e83f7 B1 21:38
> e733a59 A2 21:39
> def1981 A1 21:37 <== マージ先のコミット(ハッシュが変わる)

GitHub でサンプルを見る

マージメッセージ

マージコミットのメッセージは Settings ページで変更できます。

選択肢がたくさんあるので表にまとめました。動作確認用に使ったプルリクエストはタイトルを PR-A {メッセージの種類} と統一しています。

マージの動作	メッセージの種類	Commits ページの表示
Merge	`Default message`
Merge	`Pull request title`
Merge	`Pull request title and description`
Squash	`Default message`
Squash	`Pull request title`
Squash	`Pull request title and commit details`
Squash	`Pull request title and description`

GitHub でサンプルを見る | Merge
GitHub でサンプルを見る | Squash

一見すると同じに見えるマージメッセージですが、マージコミットのボディ部分が異なります。

Default message

Pull request title

Pull request title and commit details

Pull request title and description

考察

マージについて調べようと思ったきっかけは、どのプルリクエストをどの順番でマージしたのかサマリを見たいと思ったことでした。

この用途だと、プルリクエストごとにマージコミットが作成される「Squash and merge」が良さそうだということになります。ですが 1 コミットに集約されることで、本来のコミットごとの作業履歴が見られなくなる、単一のコミットでリバートできなくなる、などデメリットもあるようです。たとえば release ブランチにマージする時だけ「Squash and merge」を適用できたら嬉しいのですが記事執筆時点（2025/12）ではブランチごとのコントロールはできないようでした。

せっせとキャプチャをとってまとめましたが結論はデフォルトのまま現状維持、いずれまた検討する時がきたらこのブログを見に来ます。

暗黙知が支える技術の本質 | QUARTETCOM TECH BLOG

Fri, 10 Oct 2025 00:00:00 +0900

ソフトウェア開発の現場では、属人化を避けるために「なんでもドキュメント化しよう」という文化がよく見られます。
ナレッジを共有し、誰がいなくなっても困らないチームを作るという考え方自体は、合理的で正しいものだと思います。

しかし、「なんでもドキュメント化しよう」という文化は、捉え方次第では技術の習得という観点で思わぬ弊害を生むことがあります。

属人化とドキュメントのジレンマ

例えば、あるプロジェクトの環境構築の手順をまとめたドキュメントがあるとします。
そのドキュメントの内容は、何のために、どこまで詳細に書くべきでしょうか。
その線引きは、チームの方針やメンバーに求めるスキルレベルなどによって大きく異なります。

手順を細かく書けば、誰でも手順通りに作業でき、効率的に環境構築を進められます。
もし途中で問題が発生したとしても、そういったケースのトラブルシューティングの手順も記載しておけば問題ないでしょう。

しかし、そのようなドキュメントに完全に頼って環境構築を終えたメンバーは、「自走して環境構築ができた」と言えるでしょうか。
多くの場合、それは「再現できた」にすぎず、「理解して環境構築できた」とは異なります。

ドキュメントが過度に充実してマニュアルのようになると、「なぜそうするのか」を考える機会が失われます。
チーム全体がそれを当然のように良しとし、盲目的にドキュメント化を推進していると、将来的にメンバーの技術習得が課題になったり、評価と自己認識のズレや、学習意欲の低下といった問題が生じるかもしれません。

技術の習得には、思考の身体化が必要

ドキュメントは形式知を伝えるための手段としてとても有効ですが、それだけでは技術を習得することはできません。

技術を習得するということは、単に知識を得ることではありません。
知識や経験をうまく繋げ、状況に応じて適切に判断するための思考を身体化することが必要です。

開発者としてある程度経験を積むと、「この実装はなぜ気持ち悪いのか」「なぜ今はこの構成のほうが良いのか」といった、言語化しづらい感覚的な知識（暗黙知）を得て、それに基づいた判断ができるようになります。

この暗黙知は、どれだけ充実したドキュメントを読んでも得ることはできません。
仮に「なぜそうするのか」まで書かれていても、それを形式的に知るだけでは、思考の再現には至りません。

暗黙知についての有名な例えである「自転車の乗り方」（自転車の乗り方は実際に自転車に乗ることでしか知ることができず、どのように操作すれば良いかを言語化して説明することが難しい）と同じように、技術もまた、手と頭を動かし、試行錯誤するプロセスを通じてしか身につきません。
うまくいったり、うまくいかない経験のなかで生まれる感覚が、技術者としての「地力」となっていきます。

暗黙知は、文化として残す

「属人化を避けよう」というスローガンの背景には、「個人への依存を減らそう」という意図があると思います。
しかし、開発をうまく進めるための本質的な知識の多くは、個人の経験からでしか獲得できない暗黙知にあります。

本当に強いチームとは、単に手順が共有されているチームではなく、暗黙知を文化として共有できるチームです。
ドキュメントは形式知を必要な分だけ残すことに留め、設計思想、デバッグの勘所、コードの美学といった暗黙知は、ペアプロ・コードレビュー・日常的な対話などを通して受け継いでいくことが大切です。

一緒に手を動かし、考え方や価値観を自然に共有できる時間を増やすことが、結果的にチームを強くします。

終わりに

「できる」や「できるようになった」という感覚や手応えがあると、プロセスを楽しめたり、より創造的になれたりします。

今回の記事では、ドキュメント化の具体的な方法までは踏み込めませんでしたが、今後は「強いチームをつくるためのドキュメントとは何か」を意識して考えていきたいと思います！

独自のドメインモデルを捨てて、外部のドメインモデルに従う提案 | QUARTETCOM TECH BLOG

Wed, 01 Oct 2025 00:00:00 +0900

はじめに

担当しているプロダクトには 「広告を入稿する」機能 があり、これは社内のユーザ部門の業務効率化が主な目的です。

今までのフローとして、お客様に「広告設定確認書」という書類を提出して、
その「広告設定確認書内の広告設定」を元に「当該の広告媒体へ入稿を行う」業務フローがありました。

このフローをシステム化することで、業務効率を上げていました。システムの内部の処理は、「独自ドメインモデル(広告設定確認書内の広告設定)」を定義し、それを「外部ドメインモデル（媒体API・SDK）」に変換して入稿 API を叩く、という二段構えのフローを採用していました。

このプロダクトを運用していくうちに、運用においても開発においても課題が見えてきました。

プロダクトの課題

「独自ドメインモデル(広告設定確認書内の広告設定)」 を 「外部ドメインモデル (媒体API・SDK)」 に変換する際に、スキーマの不一致によってデータの互換性が取れず、API エラーが起きやすい
「独自ドメインモデル」、「外部ドメインモデル」と理解するモデルが2つあり、認知負荷が高い
データ互換性維持のための差分対応が属人化し、特定の人しか直しづらい状態になっている

まとめると「認知負荷が高い」と「データ互換性維持が困難」、「独自ドメインモデルに属人性がある」という課題 がありました。
また、広告媒体 API はアップデートされる機会が多く、このような問題に陥るケースが多くありました。

そのことから、現状の設計を根本から見直して、課題を解決する方法を考えました。

実装した設計

コンセプト

「外部ドメインモデル駆動」 とする設計です。
外部ドメインモデルの変化をシステムがしっかりと影響を受けて、システムが変化する ことを狙っています。

つまり外部のドメインモデルに主体性があります。

API 更新頻度が高いため、ACL 層を維持して独自ドメインモデルを管理するよりも、外部ドメインモデルに直接追従する方が、全体のコストを下げて安定運用できると判断して、 ACL 層を外す判断をしました。

これは一般的な設計の方針から外れる大胆な判断ですが、「API に追従することが最優先の領域」 では合理的だと考えました。

その他のコンセプトを箇条書きすると以下となります。

特定のオブジェクトのスキーマ(今回で言うと入稿 API を実行する際に必要なオブジェクト)を外部ドメインモデルに寄せている
SDK のスキーマをミラー(写像)した Interface を定義している
- その Interface を持つオブジェクトを各層に実装する
  - Infrastructure 層
    - API や SDK とやり取りする層
  - Presentation 層
    - フロントエンドの関心を持つ層
      - バリデーションの定義を持つ
      - API スキーマとして表に出す層
  - Entity 層
    - DB に保存する関心を持つ層
- いずれの層は同じインターフェース(スキーマ)が実装されているので「オブジェクト to オブジェクト」のような変換が容易。
  - フロントエンドで来たものを Entity 層に変換したり、Infrastructure 層に変換して API の実行ができたりと、レイヤーの意味を考えながら実装ができる
本来あるはずの Anti-Corruption Layer (ACL) 層を外して、外部ドメインモデルのスキーマを自システムに影響を反映させる

また「SDK のスキーマをミラー(写像)した Interface」は以下のように「getter」を定義して、スキーマの互換性を表現しています。

interface CampaignInterface {
    public function getName(): ?string;
    // SDK スキーマと同じフィールド
}

気をつけていること

SDK のオブジェクトを「我々のコード」に注入せず、SDK のスキーマをミラー(写像)した Interface に依存している
- SDK のオブジェクトは基本的に使いづらかったり、実装が汚れがちであるため、Infrastructure 層だけ SDK のオブジェクトを扱うようにして、実装の汚れを閉じ込めている
- いわば「依存関係逆転の原則(DIP)」を取り入れて、「SDK -> Interface -> Domain」の関係性を作っています。

この設計を取り入れるメリット

API 更新への追従が容易になる
- API の更新内容を見て、変更があれば「我々のシステムの外部ドメインモデルを変更する」、という一対一の関係ができる
属人化を排除できる
- モデルの説明を媒体ドキュメントに委譲できる。
データの互換性の維持が容易になる
- 抽象層(独自ドメインモデル)を介さず、媒体スキーマに準拠しているため、適合性が高くできる

この設計を取り入れるデメリット

「外部ドメインモデル（媒体API・SDK）」の理解が必要
- ただし、これは広告運用プロダクトを扱う以上、避けられない前提知識でもある
「外部ドメインモデル（媒体API・SDK）」が廃止した時、プロダクトの改修範囲が大きくなる
外部ドメインモデルをそのままコピーするのでファイル数が膨大になる
SDK 側の仕様変更に強く依存するため「ドメイン固有の最適化」がやりにくい
- 例：「API のマイクロバジェット値(マイクロ単位の通貨値)」をシステムでは「円」として保存しておきたいなど
元々存在した「独自ドメインモデル(広告設定確認書内の広告設定)」を使わなくなったため、ユーザ部門のコントロール性が下がった。（ただし、今回の設計変更は、ユーザ部門の負うこととなるこの「デメリット」を許容してもらうことをまず合意したうえでとりかかった）
- ユビキタス言語もロストしているため、業務の影響は多少なりとも出ている
- 正規化したと考えても良いが、業務をシステム都合で変えてしまっているのは変わりがない

まとめ

抽象化は一見便利ですが、常に媒体 API に追従しなければならないシステムにおいては、むしろ負債 になりがちです。

一方で、抽象化することで 1 つのモデルで他媒体の関心を共通化できるメリットもあるので、
どの選択をしてもリスクとリターンがあると、総括して感じました。

今回の設計は独自のドメインモデルを捨てて外部ドメインモデルに従う、いわば「逆DDD」ですが、
認知負荷の低減・属人化の排除・最新 API への追従を考えると、やはりメリットが多いと感じます。

そのことから「むしろ API にしっかりと追従する必要があるシステムには逆DDD が良い」という提案をしました。

実際に、この設計を今のプロダクトに適応している最中ですが、 API の追従がしやすかったり、スキーマに互換性があるため、API を叩きやすかったりと効果的だと感じています。

とはいえ、知れ渡っている理論を逆行する設計なので、心理的にも思い切りが必要です。
そのため 「逆DDD」を採用する時は、しっかりと「そのシステムで何をしたいのか？」を明確化して判断する のをオススメします。

所感

自分でモデリングする機会が減りました。
面白いところだと思いますが、少し残念です。

ひたすら外部ドメインモデルのリファレンスを読んで、
インターフェースやクラスを書いているので、作業感がとてもあります。
(かなり膨大なので疲れます)

それでもシステムは安定してきているので、作っているシステムにとって良い設計だろうと判断しています。

Symfonyのretry_failed optionsを使って、APIリクエスト失敗時に再試行するようにする | QUARTETCOM TECH BLOG

Thu, 25 Sep 2025 00:00:00 +0900

Symfonyのretry_failed optionsを活用すると、APIリクエストが失敗した際に指数バックオフアルゴリズムによる再試行が簡単に実装できます。

本記事では、その設定方法と検証結果を紹介します :saluting_face:

指数バックオフアルゴリズム (Exponential Backoff Algorithm)とは

ネットワークやAPIリトライなどで使われる「待ち時間を指数的に増やして再試行する仕組み」です。

例えば初回 1秒 → 2秒 → 4秒 → 8秒 … のように、待機時間を指数関数的に増加させてリトライ処理をします。

過去記事「リトライ処理時の指数バックオフアルゴリズムを AWS Step Functions で実装」も参考になるので読んでみてください。
https://tech.quartetcom.co.jp/2024/10/29/exponential-backoff-step-functions/

Symfonyのretry_failed optionsの設定方法

config/packages/framework.yamlを以下のように設定します。
※Symfony 5.2以降で利用可能です。

//  config/packages/framework.yaml

framework:
    http_client:
        default_options:
            retry_failed:
                enabled: true
                max_retries: 5 # 最大リトライ回数
                delay: 1000    # 初期遅延 (ミリ秒) → 1s
                multiplier: 2  # 指数の倍率（2 なら 1s,2s,4s,8s...）
                max_delay: 64000 # 最大待機（ミリ秒）→ Memorystoreの推奨に合わせ64s上限など
                jitter: 0.1    # ジッター（0.0〜1.0、ここでは10%の揺らし）。同じタイミングで大量のリトライが発生しないようにランダムなばらつきをもたせる
                http_codes: [ 423, 425, 429, 500, 502, 503, 504, 507, 510 ] # リトライ対象のHTTPコード

特定API使用時のみリトライする場合は、scoped_clientsを使います。

framework:
    http_client:
-        default_options:
+        scoped_clients:
+            api_time.client:
+               base_uri: 'https://127.0.0.1:8000/api/time'
                    retry_failed:
                        enabled: true
                        max_retries: 5
                        ...

//src/Controller/RequestController.php

...
use Symfony\Contracts\HttpClient\HttpClientInterface:

final class RequestController extends AbstractController
{
    #[Route('/request', name: 'app_request')]
    public function index(
        #[Autowire(service: 'api_time.client')]
        HttpClientInterface $httpClient
    ): Response
    {
        //APIにアクセスする
        $response = $httpClient->request('GET', 'https://127.0.0.1:8000/api/time');
        if ($response->getStatusCode() !== 200) {
            return $this->render('request/error.html.twig', [
                'message' => 'API request failed with status code: ' . $response->getStatusCode(),
            ]);
        }

        $content = $response->toArray();
        return $this->render('request/index.html.twig', [
            'time' => $content['time'],
        ]);
    }
}

参考: https://symfony.com/doc/current/reference/configuration/framework.html#http-client

本当に指数関数的にリトライしているか検証

以下の手順で検証を行いました。

HTTP 429エラー(2リクエスト/10秒)を意図的に発生させるAPIを作成
1で作成したAPIにリクエストをするクライアントにSymfonyのretry_failedオプションを設定
リトライ処理が実際に行われているか確認

1. HTTP 429エラー(2リクエスト/10秒)を意図的に発生させるAPIを作成

composer create-project symfony/skeleton:"7.3.x" rate-limitter-example
cd rate-limitter-example/
composer require webapp
composer require symfony/rate-limiter
bin/console make:controlle ApiTimeController

// src/Controller/ShowTimeController.php

<?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException;
use Symfony\Component\RateLimiter\RateLimiterFactoryInterface;
use Symfony\Component\Routing\Attribute\Route;

final class ApiTimeController extends AbstractController
{
    #[Route('/api/time', name: 'app_api_time')]
    public function index(Request $request, RateLimiterFactoryInterface $apiTimeLimiter): Response
    {
        $limiter = $apiTimeLimiter->create($request->getClientIp());

        // consume(1)の1は消費するトークン数
        if (false === $limiter->consume(1)->isAccepted()) {
            throw new TooManyRequestsHttpException(null, 'Too Many Requests');
        }

        return $this->json([
            'time' => (new \DateTime())->format('Y-m-d H:i:s'),
        ]);
    }
}    

// config/packages/rate_limiter.yaml

framework:
    rate_limiter:
        api_time:
            # use 'sliding_window' if you prefer that policy
            policy: 'fixed_window'
            limit: 2
            interval: '10 second'

2. 1で作成したAPIを使用するクライアントにSymfonyのretry_failedオプションを設定

composer create-project symfony/skeleton:"7.3.x" clear-late-limiter
cd clear-late-limiter/
composer require webapp
bin/console make:controlle RequestController

<?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Contracts\HttpClient\HttpClientInterface;

final class RequestController extends AbstractController
{
    #[Route('/request', name: 'app_request')]
    public function index(
        HttpClientInterface $httpClient
    ): Response
    {
        //APIにアクセスする
        $response = $httpClient->request('GET', 'https://127.0.0.1:8000/api/time');
        if ($response->getStatusCode() !== 200) {
            return $this->render('request/error.html.twig', [
                'message' => 'API request failed with status code: ' . $response->getStatusCode(),
            ]);
        }

        $content = $response->toArray();
        return $this->render('request/index.html.twig', [
            'time' => $content['time'],
        ]);
    }
}

//  config/packages/framework.yaml

framework:
    http_client:
        default_options:
            retry_failed:
                enabled: true
                max_retries: 5 # 最大リトライ回数
                delay: 1000    # 初期遅延 (ミリ秒) → 1s
                multiplier: 2  # 指数の倍率（2 なら 1s,2s,4s,8s...）
                max_delay: 64000 # 最大待機（ミリ秒）→ Memorystoreの推奨に合わせ64s上限など
                jitter: 0.0    # ジッター（0.0〜1.0、ここでは10%の揺らし）。同じタイミングで大量のリトライが発生しないようにランダムなばらつきをもたせる
                http_codes: [ 423, 425, 429, 500, 502, 503, 504, 507, 510 ] # リトライ対象のHTTPコード

上記の設定で指数関数的にリトライするように設定します。今回は検証結果がわかりやすいように、jitter: 0.0とします。

3. リトライ処理が実際に行われているか確認

symfony server:startで各サーバを立てます。以下

https://127.0.0.1:8000 API側
https://127.0.0.1:8001 クライアント側

とします。

https://127.0.0.1:8001/request に短時間に連続してアクセスしてみます。

その後、クライアント側のProfiler > HTTP Client > Responseを確認すると以下のことがわかります。

"retry_count" => 4より、4回リトライし、5回目で成功している
"retries"より、各リトライが1秒後 → 2秒後 → 4秒後 → 8秒後と指数関数的に試行されている

[▼
  [▼
  "info" => [▼
    ...
    "debug" => """
      ...
      * Request completely sent off
      < HTTP/2 200 
      < cache-control: no-cache, private
      < content-type: application/json
      < date: Mon, 22 Sep 2025 01:37:56 GMT
      ...
  ]
  "retry_count" => 4
  "response_headers" => [▶]
  "response_json" => [▶]
  "retries" => [▼
    [▼
      ...
      "debug" => """
        ...
        * Request completely sent off
        < HTTP/2 429 
        < cache-control: no-cache, private
        < content-type: text/html; charset=UTF-8
        < date: Mon, 22 Sep 2025 01:37:41 GMT
        ...
    ]
    [▼
      ...
      "debug" => """
        ...
        * Request completely sent off
        < HTTP/2 429 
        < cache-control: no-cache, private
        < content-type: text/html; charset=UTF-8
        < date: Mon, 22 Sep 2025 01:37:42 GMT
        ...
    ]
    [▼
      ...
      "debug" => """
        ...        
        * Request completely sent off
        < HTTP/2 429 
        < cache-control: no-cache, private
        < content-type: text/html; charset=UTF-8
        < date: Mon, 22 Sep 2025 01:37:44 GMT
        ...
    ]
    [▼
      ...
      "debug" => """
        ...
        * Request completely sent off
        < HTTP/2 429 
        < cache-control: no-cache, private
        < content-type: text/html; charset=UTF-8
        < date: Mon, 22 Sep 2025 01:37:48 GMT
        ...
    ]
  ]
]

まとめ

今回の検証では、2リクエスト/10秒という制限のあるAPIに対して、delay: 1000(=1秒)・multiplier: 2に設定したところ、リトライが頻繁に発生し、設定した最大リトライ回数（max_retries）に達してしまうケースがありました。

このため、API側のレート制限に合わせて、delayやmultiplier、max_retriesなどのパラメータを適切に調整することが重要です :warning:

Symfonyのretry_failed optionsを活用すれば、指数バックオフアルゴリズムによるリトライ機能を簡単に設定できます！ぜひ皆さんのプロジェクトでも取り入れてみてください :heart_hands:

PHPでGraphQLサーバー構築入門：Symfony＋API Platformを活用した実践 | QUARTETCOM TECH BLOG

Fri, 15 Aug 2025 00:00:00 +0900

近年のWebアプリケーションでは、画面構成やUXの多様化にともない「より柔軟で効率的なデータ取得」の重要性が高まっています。

特にフロントエンドでは、不要なデータ取得や複数回のAPIリクエストが開発体験やパフォーマンスに影響を与えるケースも増えてきました。

よく使われているREST APIでは、エンドポイントごとに決まったレスポンスが返ってくるため、フロント側の要件に合わせて「不要なデータを受け取る」や「複数のエンドポイントを呼び分ける」 といった非効率が発生しがちです。

これらの課題を解決する手段として注目されているのがGraphQLです。

GraphQLを使えば、クライアントが必要なデータだけを明確に指定して取得できるため、通信の無駄が減り開発効率やパフォーマンスの向上につながります。

本記事では、Symfony と API Platformを使って、GraphQL APIを簡単に作成する方法を紹介します。

✅️ 今回作成するもの

今回は「書籍（Book）」と「レビュー（Review）」のデータを扱うGraphQL APIを作成します。

書籍一覧の取得
各書籍に紐づくレビューの平均スコアの取得
React + Apollo Clientを使ったフロントエンドでのデータ取得

フロント以外のコードはGitHubに公開していますので、ぜひ参考にしてください。

🔗GitHub：symfony-api-platform-graphql

1. Symfonyプロジェクトのセットアップ

使用バージョン：

PHP:v8.2.28
Symfony:v7.3.1

まずは新規プロジェクトを作成します。

$ symfony new symfony-api-platform-graphql

2. API Platformの導入

API Platformは、PHP製のWeb APIフレームワークです。導入するだけで自動的にRESTとGraphQLのAPIエンドポイントが作成されます。

$ composer require api

これだけで/apiにアクセスすると、Swagger UIでREST APIのドキュメントが確認できます。

💡 API Platform では、REST API と GraphQL API の両方を併用できます。エンティティを定義するだけで、自動的に REST のエンドポイントが生成され、Swagger UI から確認や操作も可能です。本記事では GraphQL をメインに扱いますが、動作確認も兼ねてデータ登録には REST API を使って進めていきます。

3. データベース接続（PostgreSQL）

.envファイルを編集し、PostgreSQLに接続できるように設定します。

- DATABASE_URL="postgresql://app:!ChangeMe!@127.0.0.1:5432/app?serverVersion=16&charset=utf8"
+ DATABASE_URL="postgresql://app:!@127.0.0.1:5432/symfony-api-platform-graphql?serverVersion=16&charset=utf8"

ユーザー名やパスワードは自分の環境に合わせて変更してください。
事前にPostgreSQLをインストールしておく必要があります。
PostgreSQL の代わりに SQLite や MySQL を使っても大丈夫です。

その後、以下のコマンドでデータベースを作成します。

$ php bin/console doctrine:database:create

4. Book / Reviewエンティティの作成とマイグレーション

まずは開発用にMakerBundleを追加します。

$ composer require symfony/maker-bundle --dev

次に、書籍（Book）とレビュー（Review）のエンティティを作成し、マイグレーションを実行します。

$ php bin/console make:entity
$ php bin/console make:migration 
$ php bin/console doctrine:migrations:migrate

👇️️ エンティティ定義のコード

反映後、/apiにアクセスすると、BookとReviewのエンドポイントが自動生成されていることが確認できます。

次に、実際にBookとReviewのデータをAPI経由で登録してみます。

5. データ登録 (REST API)

生成された/apiエンドポイントに対して、Postmanなどを使ってデータを登録します。

Bookデータを登録するために、以下のように/api/booksにPOSTリクエストを送信します。

{
    "isbn": "978-4-7741-8411-1",
    "title": "ドメイン駆動設計入門",
    "description": "DDDの基礎を学べる書籍です。",
    "author": "山田太郎",
    "publicationDate": "2024-05-01T00:00:00+09:00"
}

Reviewデータの登録も同様に/api/reviewsにPOSTリクエストを行います。

{
    "rating": 5,
    "body": "とても分かりやすい内容でDDDが理解できました！",
    "author": "読者A",
    "publicationDate": "2024-05-10T00:00:00+09:00",
    "book": "/api/books/1"
}

データベースにデータが入っていることが確認できます。

サンプルデータとしてBookとReviewデータをいくつか登録しておきます。

サンプルデータはREADME.mdに記載しておきます。

REST APIが問題なく動作することを確認できたので、ここからは本題であるGraphQLの利用方法を見ていきます。

6. GraphQLの有効化

GraphQLを有効化します。

$ composer require api-platform/graphql

これで/graphqlにアクセスすれば、GraphiQL（GraphQL IDE）が利用可能になります。

7. GraphQLで書籍一覧を取得

API Platformでは、GraphQLエンドポイント（/graphql）が自動で用意されており、ブラウザからGraphiQLを使ってクエリを試すことができます。

まずは、シンプルに書籍の一覧を取得してみます。

query {
  books {
    edges {
      node {
        id
        title
        author
        isbn
        description
        publicationDate
      }
    }
  }
}

このように、GraphQLでは必要なフィールドだけを指定して取得できるのが大きなメリットです。

edges > nodeという構造は、Relay仕様に沿ったページネーション形式です。

👇️️ 結果画面はこんな感じ

8. カスタムフィールド（レビューの平均スコア）を追加

クライアントでレビューを集計するのは手間なので、バックエンドで平均スコアを計算して返すようにします。

📌 Bookエンティティに集計ロジックを追加

#[Groups(['book:read'])]
public function getAverageRating(): ?float
{
    if (!is_iterable($this->reviews) || count($this->reviews) === 0) {
        return null;
    }

    $sum = 0;
    $count = 0;
    foreach ($this->reviews as $review) {
        $sum += $review->rating;
        $count++;
    }

    return $count > 0 ? round($sum / $count, 2) : null;
}

レビューが存在する場合だけ平均を計算し、小数第2位で丸めて返すというシンプルな実装です。

📌 GraphQLでフィールドを有効化する

このaverageRatingをGraphQLのレスポンスに含めるためには、ApiResourceにグループ指定を追加します。

#[ApiResource(normalizationContext: ['groups' => ['book:read']])]

これでGraphQL側でも以下のようなクエリで取得可能になります！

query {
  books {
    edges {
      node {
        title
        averageRating
      }
    }
  }
}

👇️️ 結果画面はこんな感じ

バックエンドで集計処理を済ませておけば、フロント側はaverageRatingをクエリに追加するだけで、すぐに表示できます。

REST APIでも集約済みのデータを1リクエストで取得することは可能ですが、事前に専用のエンドポイントを用意する必要があり画面ごとのデータ要件に応じて設計が増えていきがちです。

その点GraphQLでは、クライアントが欲しい形で柔軟にクエリを定義できるため、バックエンド側は汎用的なスキーマを用意するだけで済みます。

その結果、クライアントは欲しいデータを、欲しい形で取得できるようになり、バックエンド側も汎用的なスキーマ設計だけで済むため、API設計の手間を大きく減らすことができます。

GraphQL のこうした柔軟さは、複雑な画面構成や多様なデータ要件を持つアプリ開発において、特に効果を発揮します。

9. フロント側からデータを取得する

GraphQLの大きな利点のひとつが、「フロントエンドから必要なデータだけを効率的に取得できる」点です。

ここではReact + Apollo Clientを使って、書籍のタイトルと平均スコアを表示するシンプルなUIを作ってみます。

GraphQLクエリの定義

const GET_BOOKS = gql`
  query {
    books {
      edges {
        node {
          id
          title
          averageRating
        }
      }
    }
  }
`;

コンポーネント側の実装

import { gql, useQuery } from '@apollo/client';

const BookList = () => {
  const { loading, error, data } = useQuery(GET_BOOKS);

  if (loading) return <p>読み込み中...</p>;
  if (error) return <p>エラー: {error.message}</p>;

  return (
    <ul>
      {data.books.edges.map(({ node }: any) => (
        <li key={node.id}>
          {node.title} - 平均スコア: {node.averageRating ?? '評価なし'}
        </li>
      ))}
    </ul>
  );
};

export default BookList;

このように、GraphQLクエリを使ってフロント側で必要なフィールドだけを柔軟に取得できます。

バックエンド側でGroups属性によってフィールド公開範囲を調整できるのも、API Platform の便利な点です。

10. まとめ

今回の構成（Symfony + API Platform + GraphQL）を振り返ってみると、こんな強みがありました。

✅ 自動生成：エンティティ定義だけでREST/GraphQL APIを即構築可能
✅ 柔軟性：Groups属性で公開フィールドを制御したり、フロントエンドから必要なデータを自由に取得できる
✅ 効率性：GraphQL により、必要な情報だけを最小限で取得できるため、通信や処理の無駄がない

GraphQLが初めての方でも、API Platformを使えば簡単に構築できます。

特に、データの粒度を調整したい場面や複雑な画面構成を持つSPA開発においては、GraphQLのメリットを最大限に活かせます。

今回は実装中心の紹介でしたが、GraphQLはUIの多様化に柔軟に対応できる強力な選択肢です。

ぜひ一度、試してみてください！

📚️ 参考リンク

Angularリアクティブフォームの型安全な使い方 ─ 罠を避ける実践ポイント | QUARTETCOM TECH BLOG

Fri, 01 Aug 2025 00:00:00 +0900

はじめに

今年に入りチーム編成が変わり、バックエンドエンジニアからフロントエンドやインフラも触ることになりました。詳しくはこちらをご覧ください。

その中でAngular v18環境でのフォーム実装に関わる機会があり、特にリアクティブフォームの「型の付け方」や「構成パターン」で混乱があったので、本記事ではTyped Forms(型付きフォーム)におけるフォームオブジェクトの生成、型推論、および nonNullable の扱いなどを体系的に整理し、より型が安全なフォーム実装に必要な観点をまとめます。

Angularのフォーム構成の方法

Angularにはフォームを作成するための2つの主要な構成方法があります。

公式ドキュメントを見ていただければわかりますがデータフローや入力フィールド数の規模感の違いなどがあり、フォームの構造やロジックの定義箇所、型推論の取り扱いが選定時に特に重要になると感じました。

リアクティブフォーム：フォーム構造・ロジックをTypeScript側で定義する。
テンプレート駆動フォーム：フォーム構造・ロジックをHTMLテンプレート側に記述する。

本記事では、Typed Forms(型付きフォーム)を活かせるリアクティブフォームに焦点を当てて解説します。

リアクティブフォームの構成要素

フォームの実装をする上で良いとされる構成パターンはよく見かけますがなぜいいのかがわからない状態だったので、以下の3つの観点に分けて順に理解していくとわかりやすいと感じたので構成方法や型指定方法の違いによって起きうる危険性も含めて解説していきます。

フォームオブジェクトの作成方法
フォームの型の指定方法
オプション設定

フォームオブジェクトの生成方法

オブジェクトの作成には、主に以下の方法があります。

フォームの基盤となるクラスをnew(インスタンス化)して作成する方法(以下、「ローレベルAPI」)
Angularが提供するユーティリティサービスのFormBuilderを使用して作成する方法

以下にそれぞれのサンプルコードを示し違いを説明します。

他にも深いところで違いがあるんだとは思いますが、個人的にはDIでのテストのしやすさや可読性の点からFormBuilderの方が好みでした。

ローレベルAPIのサンプルコード

フォームの基盤クラスであるFormGroupやFormControlを明示的にインスタンス化してフォームを作成します。

export class UserFormComponent {
    userForm = new FormGroup({
        name: new FormControl(''),
    });
    ...
}

FormBuilderのサンプルコード

FormBuilderを使用してフォームを作成します。

export class UserFormComponent {
    constructor(private fb: FormBuilder) {}
    userForm = this.fb.group({
        name: this.fb.control(''),
    });
    ...
}

フォームの型指定方法

上記で作成したフォームに型を指定する方法として、v14以降に導入されたTyped Forms(型付きフォーム)を使用することでより型安全なフォームの実装が可能になります。

Typed Forms(型付きフォーム)を使っていて最も混乱したのが、開発者が指定した型と型推論の違いでした。型パラメータやNonNullableFormBuilderを使うことでより開発者が明示的に扱う型を宣言することができ、より型安全なフォームの実装が可能になります。ですが、フォームのFormControlがnullを許容するかどうかによって意図しない型推論が行われることがあるので注意が必要です。

以下に分けて解説します。

nullを許容しない場合
nullを意図して許容する場合
nullを意図せず許容してしまっている場合

nullを許容しない場合

nullを許容しない場合は、NonNullableFormBuilderと型パラメータ<T>使うことでシンプルにより型安全なフォームを作成できます。

userForm = this.fb.group({
    name: this.fb.control<string>(""),
});

constructor(private fb: NonNullableFormBuilder) {}

FormGroup<{   
    name: FormControl<string>
}>

明示した通り<string>の型パラメータを指定することで、nullを許容しない型(FormControl<string>)として推論されます。

nullを許容する場合

nullを許容する場合は、以下のようにFormBuilderと型パラメータ<T>を使ってフォームを作成できます。

userForm: FormGroup<{
    name: FormControl<string | null>;
}> = this.fb.group({
    name: this.fb.control<string | null>(""),
});

constructor(private fb: FormBuilder) {}

FormGroup<{
    name: FormControl<string | null>
}>

これは記述通りの型推論になっており、FormControl<string | null>のようにnullを許容する型として推論されます。

nullを意図せず許容してしまっている場合

nullを意図せず許容してしまっている場合は、以下のようにFormBuilderで明示的に<string>の型パラメータを与えているように見えて、内部的なFormControlの仕様によってnullが許容されてしまいます。

userForm: FormGroup<{
    name: FormControl<string>;
}> = this.fb.group({
    name: this.fb.control<string>(""),
});

constructor(private fb: FormBuilder) {}

FormGroup<{
    name: FormControl<string | null>
}>

fb.control<string>で型パラメータを<string>で与えているのでnullは許容されていないように見えますが、AngulerのFormControlの仕様によって、nullが許容されてしまいます。

以下はFormControlの該当するソースコードです。

control<T>(
    formState: T | FormControlState<T>,
    validatorOrOpts?: ValidatorFn | ValidatorFn[] | FormControlOptions | null,
    asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null
): FormControl<T | null>;

control<T>で<T>を型パラメータとして与えても返り値は<T | null>になっていることがわかります。上記のように型パラメータだけではnullが許容されている状態となりコンパイルエラーやバグの原因になります。

これを回避するためにオプション設定を理解しておくことが重要です。

オプション設定

FormControl() や fb.control() では、第2引数として構成オプションを渡すことができます。 nullを許容しないようにするためには、nonNullable: trueオプションを指定します。

nullを意図せず許容してしまっている場合にオプションを追記すると以下のようになります。

userForm = this.fb.group<{
    name: FormControl<string>;
}>({
    name: this.fb.control<string>("", { nonNullable: true }),
});

constructor(private fb: FormBuilder) {
    this.userForm = this.fb.group({
        name: this.fb.control<string>("", { nonNullable: true }),
    });
}

FormGroup<{   
    name: FormControl<string> 
}>

nonNullable: trueを指定することで、返り値のFormControl<T|null>の型がFormControl<T>に変わり、nullを許容しないことで型安全性を高めることができます。

以下はnunNullable: trueを設定した場合のソースコードです。先ほどのnonNullableのオプション設定のないソースコードと比べると、返り値がFormControl<T|null>ではなくFormControl<T>になっていることがわかります。

control<T>(
    formState: T | FormControlState<T>,
    opts: FormControlOptions & {
        nonNullable: true;
    }
): FormControl<T>;

オプションを使うことでnullを許容しないようにすることはできますが、より型安全なフォームを実装したい場合はnullを許容しない場合でフォーム作成をすることで型安全性を高めることができます。

まとめ

リアクティブフォームは柔軟性が高いため設計を曖昧にしたまま進めると、型の不一致や型推論のnullによるバグが発生しやすくなる印象を受けました。そのため最初にフォームオブジェクト+型パラメータ+オプション設定を実装の意図に合わせて組むことが、型安全性とテスト容易性を高めるために重要だと感じました。

本記事では触れませんでしたが、interface で値の型を明示したり、FormBuilder.nonNullable.group() を使ったりすることでも型の安全性を担保できます。またリアクティブフォームに触れる中で、RxJSによる非同期処理やストリームの考え方(Observableのpipe()を使ったオペレーター連結など)も非常に新鮮に感じたのでまた紹介できればと思います。

おまけ

v13以前での型の戻り値

ブログを書く中でわかったことですがv13以前ではFormGroupやFormControlに対して型パラメータ<T>を与えることができず、戻り値はFormGroup<any>と返ってきていたようで完全に型安全にしたい場合は、ngx-typed-formsなどのライブラリを使う必要があったようです。この問題はv14でTypedFormsが公式に導入されたことで解消され、今はFormGroup<T>やFormControl<T>による型安全なフォームが標準機能として扱えるようになっています。詳しくはこちらを参照してください。

プロダクトチーム制への移行とユーザー部門との連携強化に取り組みました！ | QUARTETCOM TECH BLOG

Fri, 27 Jun 2025 00:00:00 +0900

今回は、システム開発部が現在取り組んだ「チーム体制の見直し」と「他部署との連携強化」についてご紹介します。

前提

私たちは大きさの異なるプロダクトや担当業務を合計で約20ほどを開発・運用しています。そのほとんどがいわゆる Web+RDBMS で構成されるアプリケーションですが一部は Node.JS on AWS Lambda だったり Google Apps Script だったりします。

旧体制における課題：職能別チームの状況

これまでのシステム開発部は、PHP、UI、インフラといった職能別の専門チームで構成されていました。各チームは、それぞれの専門分野を担当する数名のメンバーで構成されていました。この体制には、いくつかの課題がありました。

課題例1: チーム間での業務量のばらつき

チームによって担当するタスクの質と量にばらつきが見られました。これにより、メンバー個々の価値提供の機会に偏りが生じ、必ずしも健全とは言えない状況でした。

課題例2: プロダクトオーナーシップの不明確さ

特定のプロダクトに対し、複数の職能チームのメンバーがその都度対応する形となっていました。そのため、各プロダクトを主体的に担当するメンバーやチームが明確ではなく、結果として責任の所在が曖昧になる傾向が見られました。

新体制：プロダクトチーム制への移行

これらの課題に対応するため、私たちは組織体制を「プロダクトチーム制」へと変更しました。

プロダクトチームにはリーダーが置かれ、会社の役職上のマネージャがその職責を担います。（ちなみに各チーム名はシステム開発部の業務で欠かせない Linux のイメージキャラクタであるペンギンの種別から着想を得たものです）
各プロダクトチームには、担当するプロダクトや業務範囲が設定されています。
さらに、各プロダクトや業務範囲に対し、一人の PdM（プロダクトマネージャ）と一人以上のメンバーを明確に割り当てます。

新体制への移行により、各メンバーの権限と責任がより明確になりました。これにより、各プロダクトにおけるメンバーのオーナーシップ意識の醸成にも寄与すると考えています。一方で、従来の職能チーム体制では求められなかった、より幅広いスキルセットが各メンバーに求められるようになっています。これは、メンバー一人ひとりが専門分野を超えて成長していくことを前提としており、個人のスキル向上とキャリア形成の一助となると考えています。

新体制への過程：部門内での検討

今回のプロダクトチーム制への移行は、慎重かつ綿密な検討を重ねて行われました。私たちは、どのようなチーム構成が適切か、また各プロダクトをどのチームが担当すべきかについて、適宜さまざまな座組で複数回にわたり検討を行いました。
最終段階ではメンバー全員による複数回の協議を実施し、結論を出すための最終協議はリモートワークメンバーも含め、全員が出社して対面で意見を交換しました。忌憚のない、お互いを尊重するコミュニケーションを通じて、結論を導き出しました。検討過程でのコミュニケーションは、「変更されたチーム体制」という成果物以上に、メンバーの相互理解を深め、関係を醸成するという価値を提供してくれるものでした。この変革は、部長である私から部のメンバーに提起したものですが、各メンバーの建設的で主体的な姿勢があったことで実現できたものと認識しています。大変感謝しています！

ユーザー部門との連携強化：システム開発における共創

私たちが開発するプロダクトやタスクの大部分は、他部署の業務効率化やサポートを目的としています。そこで、ユーザー部門の従業員にもより明確なオーナーシップを持ってもらえるよう、新たな連携の枠組みを構築し始めています。
その端緒として、私からシステム開発におけるユーザー部門の従業員の関与の重要性を共有し、各プロダクトに一人の PO（プロダクトオーナー）の設定を依頼しました。
システム開発部の PdM とユーザー部門の PO が一般的に呼称される役割に限定せず、それぞれの役割を適切に協議し設定することで、プロダクトがユーザーの課題を的確に解決し、さらに効果的に利用されることを目指します。

今後の展望

プロダクトチーム制への移行とユーザー部門との連携強化は、システム開発部がより柔軟で、かつ責任を持った組織へと発展するための重要な一歩となります。この変革を通じて、私たちは今後も事業が高品質なサービスを提供するためのシステムを支えていきます！

JavaScript 非同期処理を Event Loop で理解する | QUARTETCOM TECH BLOG

Fri, 30 May 2025 00:00:00 +0900

はじめに

久しぶりに JavaScript / TypeScript に触れる機会がありました。
JavaScript の非同期処理は思い出すのにいつも時間がかかります。今後のために非同期処理について少し詳しくまとめます。

本記事では、サンプルコードとともに Event Loop の仕組み、Microtasks / Macrotasks の実行タイミングを整理しながら非同期処理についての理解を深めることを目的にしています。

本記事はおもに In depth: Microtasks and the JavaScript runtime environment を参考にしています。

Event Loop とは

JavaScript の Event Loop は、非同期処理の「実行タイミング」を制御する仕組みです。
JavaScript は（同じ Event Loop のサイクルにおいて）同期処理をすべて実行した後に非同期処理を実行します。言い換えると、非同期処理の準備が整っていても（解決済みでも）同期処理に割り込むことはありません。

同期処理 -> 即時実行される
非同期処理 -> キューに登録され、順番に実行される

非同期処理の種類（タスクの分類）

In depth: Microtasks and the JavaScript runtime environment では非同期処理を 2 種類の「キュー（待ち行列）」に分類して説明しています。

種類	名前	実行タイミング	例
Microtasks	マイクロタスク	現在のタスクの後すぐ実行	`Promise.then`, `queueMicrotask`
Macrotasks	タスク	次の Event Loop のタイミングで実行	`setTimeout`, `setInterval`

注意点

「現在のタスク（current task）」という表現が MDN にもありますが、これは setTimeout のような「Macrotasks の 1 件」だけを指すわけではありません。文脈によっては、「今 JavaScript が同期的に実行している 1 サイクル全体（＝現在の Event Loop のサイクル）」を指している場合もあります。文脈に注意して解釈する必要があります。
Macrotasks は Microtasks との対比を強調する意味で使用されることが多いようです。[In depth: Microtasks and the JavaScript runtime environment] は単に Macrotasks をTasks と表記しています。本記事は分かりやすさのために Microtasks / Macrotasks で統一します。

サンプル

今までの説明をサンプルコードを使って見ていきます。

サンプル1：基本的な実行タイミングを確認

コード

// (1)..(5) は実行順序を表します

function sampleAsynchronous() {
  return new Promise(resolve => {
      console.log('task 1.');  // (1)
      resolve('task 4.');
  });
}

const promiseObj = sampleAsynchronous();

setTimeout(() => {
  console.log('task 5.');      // (5)
}, 0);

console.log('task 2.');        // (2)

promiseObj.then(data => {
  console.log(data);           // (4)
});

console.log('task 3.');        // (3)

// 出力結果

task 1.
task 2.
task 3.
task 4.
task 5.

解説

以下の (1)…(5) はコードのコメントに記載 (1)…(5) に対応します

同期処理 (1)〜(3)：すぐに実行される
Microtasks (4)：Promise.then は Microtasks として登録され、同期処理が終わった後に即実行される
Macrotasks (5)：setTimeout は次の Event Loop サイクルで実行される

Event Loop のサイクル構造（簡略図）

 ┌────────────┐
 │ Macrotasks │ <- (1回目: 同期処理)
 └────┬───────┘
      ↓
 ┌────────────┐
 │ Microtasks │ <- (Promise.thenなど)
 └────┬───────┘
      ↓
   次の Macrotasks（setTimeout など）

サンプル2：複数サイクル実行タイミングを確認

// (1)..(10) は実行順序を表します

function createPromise() {
  return new Promise(resolve => {
    console.log('task 2.');  // (2)
    resolve('task 4.');
  });
}

function createOtherPromise() {
  return new Promise(resolve => {
    console.log('task 6.');  // (6)
    resolve('task 8.');
  });
}

console.log('task 1.');      // (1)

const promiseObj = createPromise();
promiseObj.then(data => console.log(data));  // (4)

setTimeout(() => {
  console.log('task 5.');    // (5)

  const other = createOtherPromise();
  other.then(data => console.log(data));     // (8)

  setTimeout(() => {
    console.log('task 9.');  // (9)
    console.log('task 10.'); // (10)
  }, 2000);

  console.log('task 7.');    // (7)
}, 1000);

console.log('task 3.');      // (3)

// 出力結果（順序）

task 1.
task 2.
task 3.
task 4.
task 5.
task 6.
task 7.
task 8.
task 9.
task 10.

解説

1回目の Event Loop
- Macrotasks：task 1. -> task 2. -> task 3.
- Microtasks：task 4.（Promise.then）
2回目の Event Loop（ 1000ms 後の setTimeout ）
- Macrotasks：task 5. -> task 6. -> task 7.
- Microtasks：task 8.（ Promise.then ）
3回目の Event Loop（さらに 2000ms 後の setTimeout ）
- Macrotasks：task 9. -> task 10.
- Microtasks：なし

まとめ

まとめとしてに本記事の要点を記載します。

Promise.then は同期処理が終わった直後に実行される（ Microtasks ）
setTimeout は次の Event Loop サイクルで実行される（ Macrotasks ）

Event Loop は Macrotasks（ current task ） -> すべての Microtasks → 次の Macrotasks（ Tasks ）という流れで進行します。

非同期処理は JavaScript の基本的な機能ですが、文脈による言葉の使い分け（特に「task」）も含め、分かりづらい面もあります。本記事が非同期処理の理解の一助になれば幸いです。

GitHubでYahoo!広告スクリプトのための開発環境をつくる | QUARTETCOM TECH BLOG

Wed, 05 Mar 2025 00:00:00 +0900

はじめに

みなさん「Yahoo!広告スクリプト」をご存知でしょうか。
Yahoo!広告スクリプトとは、Yahoo! JAPANにおけるWeb広告プラットフォームにアクセスするためのスクリプトです。

Yahoo!広告スクリプトとは？特徴や利用手順を解説 | LINEヤフー for business

弊社にはWeb広告の運用代行事業があり、とある集計作業でのスクリプト制作を試みました。

Yahoo!広告スクリプトは専用の編集画面でJavaScriptのコードを登録します。
リアルタイム実行またはタイマー実行で、ログを見てトライ＆エラーを繰り返すのが基本の使い方です。CI、テスト、リビジョン管理といったなじみの道具はなく、使用できるAPIや構文はECMAScriptのバージョンとは一致しません。

そんなランタイムのための開発環境をどう作るか…🤔
試行錯誤の結果できあがった開発環境について紹介します。

※ Yahoo!広告ランタイムは定期的にアップデートされます。当記事はランタイム「202501」を前提としています。

目指したもの

できるだけ普段に近づけたいと思い、以下を開発環境の要件としました。

GitHubでリビジョン管理する事
TypeScriptで開発する事
ユニットテストを実行する事
ランタイムのビルトインサービスを表現できる事
ランタイムのシンタックスエラーをローカルで再現する事
1回限りでなく既存プロジェクトへの展開ができる事

完成したもの

https://github.com/ringtail003/yas-scaffold

完成した開発環境をGitHubリポジトリにアップしました。
このリポジトリは以下のように使用します。

空のディレクトリを作成し、npxでセットアップ用スクリプトを叩くと各種設定ファイルがコピーされます。

$ node --version
> v22.9.0

$ mkdir my-project
$ cd my-project

$ npx ringtail003/yas-scaffold yas --init
> 設定ファイルをコピーしました（package.json）
> 設定ファイルをコピーしました（eslint.config.json）
> ...

プロジェクト名を書き換えてパッケージをインストールします。

// package.json
{
  "name": "my-project"
}

$ npm install

これでセットアップは完了です。
サンプルコードに対してユニットテストとLintが実行できます。

$ npm test
> ✔ src/greet.ts (72.979375ms)
>   ✔ プリミティブ (0.4155ms)
>   ✔ 配列 (0.474125ms)
> ...
> ℹ tests 13
> ℹ pass 13

$ npm run lint
> eslint --fix ./src

ビルドコマンドを叩くと、JavaScriptにトランスパイルしたビルドファイルが生成されます。

$ npm run publish
> created dist/bundle.js in 343ms
> created dist/publish.js

ビルドファイルの中身をスクリプト編集画面に貼り付けます。
保存してリアルタイム実行し、ログやリファレンスを見ながら実装を詰めていきます。

リポジトリはYahoo!広告スクリプトのプロジェクトを構成する目的として、yas-scaffold（Yahoo Ads Script Scaffold）と名付けました。以降はこのリポジトリを「YAS開発環境」と表記します。

GitHubでリビジョン管理する

ビルドファイルの冒頭にはgitのコミットが記載されます。
Yahoo!広告スクリプトの編集画面から辿ってビルド時点のコミットが特定できる、という仕組みです。

// publish.js

/**
 * @file ...
 * @see https://github.com/{SAMPLE_ORGANIZATION}/my-project/commit/123abcd
 */
function main () { ... }

コメントはビルド後に publish.sh で埋め込んでいます。{SAMPLE_ORGANIZATION} は実際には自社のOrganizationをベタ書きしていて、 my-project はビルド時にpackage.jsonから読み込みます。

Yahoo!広告スクリプトをたくさん登録しても（上限100個）、どのリポジトリで開発しているのか判別ができます。

TypeScriptで開発する

TypeScriptからJavaScriptへのトランスパイルは Rollup を採用しました。

最初は Babel を使っていたのですが、設定が圧倒的にシンプルであること、複数ファイルを結合するバンドル機能を標準で備えていること、などの優位性からRollupに乗り換えることにしました。

セットアップ用スクリプトで作成されるサンプルコードは index.ts で、開発言語はTypeScriptです。ビルドコマンドを叩くとJavaScriptのファイルが出力されます。

$ npm run build

├── dist
│   ├── bundle.js # ビルドファイル
├── src
│   ├── index.ts # ソースコード
│   └── greet.ts # ソースコード
├── rollup.config.js

設定ファイル rollup.config.js はたったの14行です。巷ではゼロコンフィグのトランスパイラも登場しているようですが、今のところRollupに満足しています。

ユニットテストを実行する

テストはNode.jsのビルトインテストランナーを採用しました。YAS開発環境では関数のIN/OUTを検証するテストが主体で、必要最低限のものが揃えば十分だと思ったからです。

テストコマンドは基本的に node --test を実行しているだけです。ビルトインテストランナーは *.test.ts を探してテストスイートを実行します。

node --test \
  --experimental-strip-types \ # 型宣言を削除する
  --experimental-transform-types \ # enumなどTypeScript独自のシンタックスを変換する
  --no-warnings=ExperimentalWarning # experimentalの警告表示をオフにする

テストのサンプルコード index.test.ts では、インポート文に .ts が付いています。Node.jsの --experimental-strip-types フラグは型宣言を削除するだけでTypeScriptのように拡張子を補完しないため、拡張子付きで宣言する必要があります。また型のインポートが削除対象となるように type キーワードも必要になります。

import { greet, type Greeting } from "./greet.ts";

インポートだけ気をつければ後は普通にテストを書くことができます。一般的なアサーションも揃っています。

import { test, type TestContext } from "node:test";

describe("...", () => {
  test("...", (t: TestContext) => {
    t.assert.equal("Hello World", "Hello " + "World");
    t.assert.deepEqual([1,2], [1,2]);

    const a = {};
    const b = a;
    t.assert.strictEqual(a, b);
  });
});

テスト環境のためのパッケージのインストールやアップデートメンテも不要ですし、ユニットテストならこれで十分かなと思っています。

※ --experimental-strip-types フラグの挙動は Node.js v23.6 でデフォルトになるため、Node.jsのアップデートとともに必要がなくなります。

ランタイムのビルトインサービス

リファレンス | Yahoo! JAPAN広告

Yahoo!広告スクリプトにはビルトインサービスが存在し、Googleスプレッドシートの書き込みやログ出力ができます。

const ss = SpreadsheetApp.openById("テスト");
Logger.log("完了");

SpreadsheetApp や Logger はYahoo!広告のランタイムで実体が得られるオブジェクトで、そのまま書くとTypeScriptの世界ではコンパイルエラーが発生します。

const ss = SpreadsheetApp.openById("テスト");
//         ~~~~~~~~~~~~~~
//         ERROR: Cannot find name 'SpreadsheetApp'.ts(2304)

YAS開発環境では、ビルトインサービスをグローバルオブジェクトとして builtin.d.ts で型宣言しています。

declare global {
  type SpreadsheetApp = {
    openById (id: string): Spreadsheet;
  };

  // グローバルオブジェクトの存在を宣言する
  var SpreadsheetApp: SpreadsheetApp;

tsconfig.json でデフォルトで読み込むようにしておけば、どのファイルからもインポート文なしで使用できます。

"compilerOptions": {
  "typeRoots": ["./types"]
}

SpreadsheetApp.openById(spreadsheetId); // 👍

テスト環境では実体が得られないため、モックをセットしておきましょう。

beforeEach(() => {
  globalThis.SpreadsheetApp = {
    openById: () => "dummy file",
  };
});

test("...", () => {
  SpreadsheetApp.openById(spreadsheetId); // 👍
});

シンタックスエラーをローカルで再現する

Yahoo!広告のランタイムとECMAScriptのバージョンは一致しません。Array.flatMap（ES2019） は使用できて、それよりも古い class（ES6） は使用できない、といった具合です。

このような環境の場合、以下のような選択肢が考えられます。

新しいバージョンをベースにしてシンタックスを個別に禁止する
古いバージョンをベースにしてシンタックスを個別に許容する

YAS開発環境では「古いバージョン」をベースにしました。新しいシンタックスをひとつずつ試して禁止していくよりも、ランタイムで大半のシンタックスが使える古いバージョンをベースにするほうが楽だからです。

tsconfig.json には、やや古めの ES6 を指定しています。

"compilerOptions": {
  "lib": ["ES6"], // ES6 === ES2015

シンタックスを禁止する（ESLint）

class（ES6） はTypeScriptではコンパイルエラーになりませんが、Yahoo!広告スクリプトのランタイムでシンタックスエラーが発生します。

class Foo {} // コンパイルエラーにならない

このようなケースでは、うっかりコードを書かないように eslint.config.js のルールで使用を禁止します。

import esPlugin from "eslint-plugin-es";

export default [
  {
    files: ["**/*.ts"],
    plugins: {
      es: esPlugin, // `es/` プレフィクスを有効にする
      ...
    },
    rules: {
      "es/no-classes": "error", // classの使用を禁止する
    },
  }
];

class Foo {}
// ~~~~~~~~~
// ERROR: ES2015 class declarations are forbidden.

シンタックスを許容する（declare宣言）

開発中に Object.groupBy（ES2024） が使いたくなることがありました。YAS開発環境はES6のため、ES2024のAPIの型は存在しません。そのまま書くと型の解決ができずコンパイルエラーが発生します。

Object.groupBy([], function () {});
//     ~~~~~~~~
//     ERROR: Property 'groupBy' does not exist on type 'ObjectConstructor'.

Object.groupBy はYahoo!広告スクリプトのランタイムではシンタックスエラーにならず、期待通りの結果が返ることが分かりました。このようなケースでは、declare宣言で型を解決します。

declare global {
  interface ObjectConstructor {
    groupBy<K, T>(...): Partial<Record<K, T[]>>;
  }
}

Object.groupBy([], function () {}); // 👍

シンタックスを許容する（Rollup）

YAS開発環境はES6のため Optional chaining（ES2020） を使うとコンパイルエラーが発生します。この構文はYahoo!広告ランタイムでもシンタックスエラーが発生し、使うことができません。

const v = foo?.bar?.value;
// ~~  ~~
// ERROR: ES2020 optional chaining is forbidden.

このようなケースでは、Rollupでポリフィルできないか探しましょう。

Rollupでは generatedCode で指定したECMAScriptのバージョンにより、一部のコードがポリフィルの対象になります。

export default {
  output: {
    generatedCode: "es5", // ES5で出力する
    ...
  },

// Before: index.ts
const v = foo?.bar?.value

// After: publish.js
(_v = foo === null || foo === void 0 ? void 0 : foo.bar) === null
  || _v === void 0 ? void 0 : _v.value;

ポリフィルできることが分かれば eslint.config.js で許容しておきましょう。

export default [
  {
    ...
    rules: {
      "es/no-optional-chaining": "off", // ルールをオフにする
    },
  }
];

const v = foo?.bar?.value;  // 👍

シンタックスを禁止する（ESLintカスタムルール）

Yahoo!広告ランタイムでは 〜 という文字が使用できませんでした。コメントアウトの中に存在していても「使用できない文字が含まれている」と保存時にエラーになる事がありました。

Yahoo!広告ランタイムの独自エラーのため、TypeScriptのコンパイルエラーでは検出できません。

Logger.log("1〜100件のデータ取得完了");  // コンパイルエラーにならない

このようなケースでは Custom Rule Tutorial を参考にしてESLintのカスタムルールを追加します。YAS開発環境では plugin.js にカスタムルール置き場を用意しています。

const plugin = {
  meta: {
    name: "eslint-plugin-no-wave-dash", // ルール名
    version: "1.0.0",
  },
  rules: {
    "no-wave-dash": { // ルールの実装
      create(context) {
        return {
          Literal(node) {
            if (node.value && typeof node.value === "string") {
              if (node.value.includes("〜")) {
                context.report({
                  node,
                  message: "Yahoo!広告スクリプトで'〜'は使えません。",
                });
              }
              ...

追加したカスタムルールは eslint.config.js で有効にします。

import plugin from "./lint/plugin.js";

export default [
  {
    plugins: {
      custom: plugin,  // `custom/` プレフィクスを有効にする
      ...
    },
    rules: {
      "custom/no-wave-dash": "error", // 禁止する
      ...
    },

このようにすると、Yahoo!広告スクリプトの独自エラーを検出できるようになります。

Logger.log("1〜100件のデータ取得完了");
//          ~~~~~~~~~~~~~~~~~~~~~
// ERROR: Yahoo!広告スクリプトで'〜'は使えません。eslint(custom/no-wave-dash)

既存プロジェクトへの展開

セットアップ用スクリプトを使うことで、同じYAS開発環境のプロジェクトをいくつも作ることができます。

$ npx ringtail003/yas-scaffold yas --init

Yahoo!広告ランタイムのアップデートでそれまで使えなかったシンタックスが使えるようになったり、Node.jsのアップデートで便利な機能が使えるようになるかもしれません。YAS開発環境もそれに合わせて進化していくでしょう。

そんな時のために更新用のスクリプトも用意しています。設定ファイルを再びリポジトリからコピーして、パッケージ更新を促すだけのスクリプトです。

$ npx quartetcom/yas-scaffold yas --update
> 設定ファイルをコピーしました（eslint.config.js）
> ...
> 
> package.json 'devDependencies' をインストールしてください
> ┌─────────┬─────────────┬─────────┬──────────┐
> │ (index) │ name        │ current │ required │
> ├─────────┼─────────────┼─────────┼──────────┤
> │ 0       │ 'package-A' │ '1.0.0' │ '3.0.0'  │
> └─────────┴─────────────┴─────────┴──────────┘
> npm install -D \
>   package-A@3.0.0

実装は yas-cli.js に存在します。package.json に登録することでnpxでの実行が可能になります。

"bin": {
  "yas": "./bin/yas-cli.js"
}

セットアップ用スクリプトで作成したプロジェクトでは、テストランナーの変更など個別のカスタマイズを想定していません。ベースとなるYAS開発環境のリポジトリに変更を加え更新用スクリプトで配布します。

このような仕組みにすることで、プロジェクトの数が増えてもYahoo!広告ランタイムやNode.jsのアップデートにかんたんに追随できると考えました。

おわりに

Yahoo!広告スクリプトに限らず、他のランタイムでも同じ仕組みで開発環境が構築できるのではないかと思います。

今回紹介した内容がどなたかのお役に立てば幸いです。

PHPカンファレンス名古屋2025 プラチナスポンサー参加レポート | QUARTETCOM TECH BLOG

Mon, 03 Mar 2025 00:00:00 +0900

PHPカンファレンス名古屋2025にプラチナスポンサーとして協賛しブース出展、スタッフとして参加しました！
初ブース出展で当日は運営スタッフとしての参加だったのでセッションは見ることができませんでしたが、PHPを扱う会社としてPHP業界に貢献できよかったです！
当日はイベント来場者がアンケートや企画参加のためにブースに来ていただきとても盛り上がったかなと思っています、ありがとうございました！

ブースアンケート集計結果

ソフトウェア開発においてAI技術の活用は全体の何%を占めていますか？

アンケート内容の定義は以下の通りです。

縦軸：自分が所属しているチーム単位の人数
横軸：その業務でAI技術を活用しているパーセンテージ

開発規模は1~10人、AI利用率は0%~50%に多く分布していたものの、その中では大きな偏りがない結果となりました。
回答者の中には、AIの利用率が低いことで謙遜する方や、逆に利用率が高いことで謙遜する方が見受けられました。また、全体としてAIの活用が思ったより進んでいるという声が多くありました。

あなたの勤務スタイルは？

最近ではフルリモート勤務からハイブリット勤務や出社勤務に戻す企業も増えている印象がありましたが、
結果を見ると、フルリモート勤務が多いという結果でした。

初ブース出展の感想

初ブース出展でしたが、PHP業界の方々と交流できてとても楽しかったです。
WebサイトをPHPを使って構築・運用されている方などには、弊社で開発しているWeb広告レポートツール(Lisket)やGoogleアナリティクスレポートツール(無限GAレポートメーカー) に関心を寄せてくださる参加者もいらっしゃいました。そのような方々と直接話すことで、ブース出展を行う企業向けのスポンサープランならではの価値を実感する場面もありました。
個人的には勉強会への企業からのスポンサーは、企業PRとPHPコミュニティーへの恩返しの意味が強いのかなと思っています。
PHPは古いと言われることも多々ありますが、多くのエンジニアに愛されている言語なんだなと実感しました。
恩返しという意味では、他にもOSSへの貢献(バグ報告やドキュメント改善など)やPHP Foundationへの寄付などがあると思いますが、PHPを使う企業に属する者としてコミュニティーへの貢献は継続的にしていけたらいいなと思います。

カルテット開発部について

カルテット開発部は、インターネット広告専門の広告代理店内の開発部門です。
少人数の部署ですが、広告運用を効率化する Lisket とウェブサイト運営に欠かせないGoogleAnalyticsのレポートをエクセル形式で出力できる無限GAレポートメーカーという2つのWebサービスを開発〜運営まで行っています。既存システムの保守だけでなく社内システムや新規事業などの新規プロダクトの開発も進行中で、直近プロダクトではスクラム開発も実施しておりました。
フルリモート勤務も可能でライフワークバランスも大切にしているので、PHPを使うエンジニアの方々にも働きやすい環境を提供できると思います。
オンラインカジュアル面談も随時受け付けているので、少しでも興味を持っていただいた方はぜひお気軽にお問い合わせください。

PHPカンファレンス名古屋2025にプラチナスポンサーとして協賛します | QUARTETCOM TECH BLOG

Thu, 20 Feb 2025 00:00:00 +0900

PHPカンファレンス名古屋2025にプラチナスポンサーとして協賛いたします。
当日はブースも構えて会場に参加しているので、ぜひ立ち寄っていただければと思います。

名古屋でのPHPカンファレンス開催は今回が初めてでカルテットコミュニケーション開発部からは運営スタッフとしても参加します！

PHPカンファレンス名古屋について

都市規模に比して不活発と言われているエンジニアコミュニティ活動を活発にしたい！
地理的な理由でこれまで各地のカンファレンスに参加できなかった地方在住のエンジニアの方の参加を通して、名古屋のエンジニアと全国のエンジニアの交流が促進され名古屋のエンジニアコミュニティにも新たな風を吹き込みたい！
そんな思いから開催されるカンファレンスです。

【概要】

日時：2025年2月22日(土)
（開場 9:30、本編 10:00〜18:00、懇親会 19:00〜21:00）
会場：ウインクあいち 11F
公式サイト：https://phpcon.nagoya/2025/
公式Twitter：https://x.com/phpcon_nagoya

カルテット開発部について

カルテット開発部は、インターネット広告専門の広告代理店内の開発部門です。
少人数の部署ですが、広告運用を効率化する Lisket とウェブサイト運営に欠かせないGoogleAnalyticsのレポートをエクセル形式で出力できる無限GAレポートメーカーという2つのWebサービスを開発〜運営まで行っています。既存システムの保守だけでなく社内システムや新規事業などの新規プロダクトの開発も進行中で、直近プロダクトではスクラム開発も実施しておりました。
PHPer絶賛募集中です！少しでも興味を持っていただいた方はぜひオフライン・オンライン両会場で弊社エンジニアにお声掛けください。

同一 MySQL サーバ上の複数データベースに対する権限設定 - Ansible mysql_user モジュールで実装する際の注意点 | QUARTETCOM TECH BLOG

Fri, 14 Feb 2025 00:00:00 +0900

結論

同一 MySQL サーバに共存させた複数データベースに存在するユーザーに対して任意の権限を付与するには、/ を使う必要があります。
Ansible の mysql_user モジュールでは、同じユーザーに対して複数回 priv を指定すると、後から指定した値が優先されるからです。

この挙動を整理した時の経緯を紹介します。

何で困っていたか

同一サーバに複数のデータベースを作成し、 Ansible を使ったユーザー作成と権限管理を行なっていましたが、この際の挙動を捉えるのに苦労しました。

例えば、user1 に対する以下のような設定を想定しているとします。

database_a の全てのテーブルに対する SELECT 権限
database_b の全てのテーブルに対する ALL 権限

この想定で playbook.yml を次のように記述した場合

      - { name: user1, state: present, host: 'localhost', priv: 'database_a.*:SELECT', password: password1 }
      - { name: user1, state: present, host: 'localhost', priv: 'database_b.*:ALL', password: password1 }

Ansible による実行結果は以下のようになり、user1 に関する database_a への権限を付与できませんでした。

mysql> SELECT Host, User, Db, Select_priv, Update_priv FROM mysql.db;
+-----------+---------------+--------------------+-------------+-------------+
| Host      | User          | Db                 | Select_priv | Update_priv |
+-----------+---------------+--------------------+-------------+-------------+
| localhost | mysql.session | performance_schema | Y           | N           |
| localhost | mysql.sys     | sys                | N           | N           |
| localhost | user1         | database_b         | Y           | Y           |
+-----------+---------------+--------------------+-------------+-------------+

実行順序を入れ替えても

      - { name: user1, state: present, host: 'localhost', priv: 'database_b.*:ALL', password: password1 }
      - { name: user1, state: present, host: 'localhost', priv: 'database_a.*:SELECT', password: password1 }

以下のような結果となり、やはり user1 に関してデータベースごとに異なる権限を付与できませんでした。

mysql> SELECT Host, User, Db, Select_priv, Update_priv FROM mysql.db;
+-----------+---------------+--------------------+-------------+-------------+
| Host      | User          | Db                 | Select_priv | Update_priv |
+-----------+---------------+--------------------+-------------+-------------+
| localhost | mysql.session | performance_schema | Y           | N           |
| localhost | mysql.sys     | sys                | N           | N           |
| localhost | user1         | database_a         | Y           | N           |
+-----------+---------------+--------------------+-------------+-------------+

上記以外にも、カンマやリストを使った記述方法も試しましたが、いずれも望んだ結果を得られませんでした。

どうやって解決したか

公式情報をちゃんと読み、簡単な検証ツールを作って検証しました。最終的に以下のような記述により、期待した結果を得ました。

      - { name: user1, state: present, host: 'localhost', priv: 'database_a.*:SELECT/database_b.*:ALL', password: password1 }

mysql> SELECT Host, User, Db, Select_priv, Update_priv FROM mysql.db;
+-----------+---------------+--------------------+-------------+-------------+
| Host      | User          | Db                 | Select_priv | Update_priv |
+-----------+---------------+--------------------+-------------+-------------+
| localhost | mysql.session | performance_schema | Y           | N           |
| localhost | mysql.sys     | sys                | N           | N           |
| localhost | user1         | database_a         | Y           | N           |
| localhost | user1         | database_b         | Y           | Y           |
+-----------+---------------+--------------------+-------------+-------------+

公式ドキュメント

Multiple privileges can be specified by separating each one using a forward slash: db.table1:priv/db.table2:priv.

https://docs.ansible.com/ansible/latest/collections/community/mysql/mysql_user_module.html#parameter-priv

検証ツール

こちらは GitHub に公開しましたので、興味のある方はご活用ください。このツールは MySQL に対する Ansible の挙動を Docker を使って確認するのに役立ちます。

https://github.com/Tatsumi-I/ansible-mysql_user-test-tool

まとめ

同一ユーザーへ複数回 priv を指定した際の挙動を理解していないと、想定した権限を付与できないことがあります。
同一サーバに共存する複数データベースにおけるユーザーへ任意の権限を付与するには、/ を使う必要があります。

また、Ansible における変数の扱いやその優先度も併せて把握することが重要です。

In general, Ansible gives precedence to variables that were defined more recently, more actively, and with more explicit scope. Variables in the defaults folder inside a role are easily overridden. Anything in the vars directory of the role overrides previous versions of that variable in the namespace.

https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#understanding-variable-precedence

どんなツールでもとっかかりは難しいですが、使えると開発者体験が大きく向上しますね。これがその一助となりましたら幸いです。

（参考）検証環境

$ docker --version
Docker version 27.4.0, build bde2b89

# mysql --version
mysql  Ver 8.0.37
# ansible --version
ansible [core 2.13.13]

意思決定を未来へ届ける | QUARTETCOM TECH BLOG

Tue, 07 Jan 2025 00:00:00 +0900

はじめに

開発部の有澤です。

数ヶ月ほど前に、社内アプリケーションの開発責任者(いわゆるプロダクトマネージャー)になりました。役割を通じて、ステークホルダーと関わることが増え、既存システムに機能を加える機会が増えてきました。

私は新たな要望に応えるため、既存システムと新規機能を比較し、「どのような設計で実現できるか」を検討する機会が増えましたが、その過程で一つの懸念が浮かびました。

システム設計書は時間と共に風化する

私がこれまでに触れてきたシステム設計書には、さまざまな形式がありました。

Excel
PowerPoint
ナレッジベース
コードベース
人の頭の中
GitHub Issue
Pull Request
Commit メッセージ
Slack メッセージ
紙

これらはチームや組織の状況に応じて形が変わるもので、どれが優れているかは一概に言えません。

しかし、共通する課題があります。それは、時間とともに「リンク切れ」「検索不可」「消失」などの問題が発生し、情報が風化する点です。また、これらの情報が分散しているため、仕様を再確認する作業がまるで「地層から化石を掘り起こし、全体像を再構築する」ような作業が必要だったりします。

私はこういった情報の復元に慣れていますが、面倒であるのは確かです。
このような状況を自分も生み出してしまうのかと思うと、どうにか解決したいと考えるようになりました。

未来人はシステム設計書で何を知りたいのか

未来の開発者が何を知りたいかを完全に予測することは難しいです。

ですが、自分やチームが「何が必要か？」を考えたり、話し合ったりはできます。
自分やチームが必要なものが書かれていれば、少なからず未来人は意思決定の参考になるはずです。

考えるに、以下のようなことだと定義しました。

なぜこの設計を採用したか？
他に代替案はなかったか？
この設計はシステムへ適応済みか？
適応したかった設計はあるか？
大小限らず、発見した技術的負債はあるか？

これらをまとめると、「意思決定の判断材料」として機能する情報 が必要だと考えました。

この情報があれば、未来の開発者がシステム変更時にスムーズな判断を下せるようになるはずです。

ADR を採用しました

ADR は比較的軽量なフレームワークだったのもあり、こちらを採用することにしました。

とはいえ ADR のテンプレートにしっかり準拠するのではなくて、必要な情報を箇条書きで書ける独自テンプレートを使用することにしました。

ドキュメントを書くためのフレームワークを調べたところ、以下がありました。

Design Doc
- システムや機能の詳細な設計を記録したドキュメントで、特定の技術的なソリューションや実装について深く掘り下げているのが特徴。
- https://www.industrialempathy.com/posts/design-docs-at-google/
Architecture Decision Records (ADR)
- システム設計における重要な意思決定を記録するための簡潔なドキュメント。
- https://adr.github.io/
Lightweight Architecture Decision Records (LADR)
- ADRの簡易版で、より軽量な記録形式。小規模なプロジェクトや頻繁な意思決定の記録に適してそう。
- https://github.com/peter-evans/lightweight-architecture-decision-records?tab=readme-ov-file

ADR の配置

PHP アプリケーションのルート直下に doc/adr/ を作成して、その中にマークダウンファイルを格納しています。

エディタ上で閲覧・編集が簡潔するので開発者的には嬉しいですし、バージョン管理されるため、ドキュメントがロストしにくくなります。

PHP Application (root)
└── doc
    └── adr
        ├── 2024-08-23-依存ライブラリの見直し.md
        ├── 2024-11-29-◯◯機能の縮小.md
        ├── 2024-12-17-ADRの導入.md
        ├── 2024-12-18-◯◯機能の再設計.md
        └── README.md
└── public
└── config
└── .dockerignore
└── etc...

アプリケーションデプロイ時にドキュメントが増えることを避けたい場合は、.dockerignore で doc/ を無視することを推奨します。

ADR のテンプレート

必要な情報を最小限に集めたいので、以下のテンプレートを定義しました。

## 背景（Background）
- 問題の概要と目的。
- システムが解決しようとする課題。 

## 目標と非目標（Goals and Non-Goals）
- 目標: このプロジェクトで達成すべきことを具体的に記述。
- 非目標: このプロジェクトでは対応しないことを明確にしてスコープを限定。

## 提案内容（Proposal）
- 問題を解決するアプローチ。
- 技術的な選択肢や、それぞれのメリット・デメリット。

## 技術設計（Technical Design）
- システムのアーキテクチャ。
- データベース設計やAPI仕様の詳細。
- PHPフレームワークや主要ライブラリの選定理由。

## 代替案（Alternatives Considered）
- 他に検討したアプローチと採用しなかった理由。
- リスクとトレードオフ（Risks and Tradeoffs）
- 現状では想定しづらいリスクや、トレードオフについて明記。

# マイルストーンとスケジュール（Milestones and Timeline）
- プロジェクトのスケジュールと各フェーズのゴール。
- 未解決の問題（Unresolved Questions）
- 現段階では結論に至っていない内容。

そもそも、ドキュメントを書くことは開発者のオーバーヘッドです。見出しに対して文字を埋めることを強要せず、必要な情報だけを書ける柔軟な形式を理想としています。

ADR の内容

まずは「ADRを導入した際の意思決定」を書くのがスタートに丁度よいです。実際の物よりもボカシていますが、以下のように書きました。

# 2024-12-17 ADRの導入

## 背景（Background）
- ◯◯ の設計や機能を変更する上で、変更箇所や理由、意思決定が継承されづらい状況であることが懸念だった。

## 目標と非目標（Goals and Non-Goals）

### 目標
- ADRを導入することで、意思決定を継承する。
  - 初期段階で完璧なADRは目指さないで、まずは簡単な形で導入を目指す。

### 非目標
- なし

## 提案内容（Proposal）
- ADRを導入
  - コードと一緒に保管される形容なら、プロダクトが生き続く限り残るのでベストと判断した。
  - エディタ内で完結することもDX的に良い。

## 代替案（Alternatives Considered）
- Notionやその他のナレッジベースで管理すること
  - リンク切れを起こしたり、そもそも形容として形骸化しやすいので避けた。

ADR のメンテナンス

「必要だと思ったり、便利だと感じる人が増えたら必然的に良いADRが残るはず」と期待しているので、メンテナンスに関するルールは定義していません。

また、ドキュメントをバージョン管理することのデメリットの一つとして「Pull Requestをレビューする必要」がありますが、 doc/ ディレクトリ配下はレビュー不要とすることで、ドキュメントのメンテナンスのハードルを下げても良いと感じています。

所感

書いた自分でも後々思うのは、代替案が書いてあるのは凄く便利です。

新たに機能を開発した後「なぜこうしなかったのか？」と話が上がることは、プロダクト開発においてよくあります。その際に自分の記憶が曖昧になっていたり、そもそも自分が退職してしまった時に説明できないのは問題だと感じていたので、 ADR を通してプロダクトの持続可能性を高められたら嬉しいです。

QUARTETCOM TECH BLOG

Symfonyの.envファイルをうっかり git プッシュから守る方法 | QUARTETCOM TECH BLOG

はじめに

.env.local を git で追跡しない：.gitignore

.env.local をコミットしない：1Password Local .env files

.env.local を作らない：Symfony’s secrets management system

プッシュをブロック：GitHub Push protection

まとめ

Claude Code 入門: 導入から基本操作・コスト管理まで | QUARTETCOM TECH BLOG

1. まず押さえたい基本概念: 「セッション」と「コンテキスト」

セッション（作業のまとまり）

コンテキスト（AI の短期記憶）

2. 初期設定: /init と CLAUDE.md

プロジェクトの「記憶」を作る /init

要件定義ファイルなどの扱い

3. うまく伝わらない時は？ コンテキスト管理のコツ

基本は /clear でリセット

コンテキストを残したいなら /compact

4. 利用状況の確認とモデルの使い分け

利用状況の確認

モデルの使い分け

5. 急な割り込み対応（セッション管理）

まとめ

GitHubのマージ（Merge Commit/Squash Merging/Rebase Merging）の違い | QUARTETCOM TECH BLOG

1) Create a merge commit

2) Squash and merge

Squash and merge の Author

3) Rebase and merge

マージメッセージ

Default message

Pull request title

Pull request title and commit details

Pull request title and description

考察

暗黙知が支える技術の本質 | QUARTETCOM TECH BLOG

属人化とドキュメントのジレンマ

技術の習得には、思考の身体化が必要

暗黙知は、文化として残す

終わりに

独自のドメインモデルを捨てて、外部のドメインモデルに従う提案 | QUARTETCOM TECH BLOG

はじめに

プロダクトの課題

実装した設計

コンセプト

気をつけていること

この設計を取り入れるメリット

この設計を取り入れるデメリット

まとめ

所感

Symfonyのretry_failed optionsを使って、APIリクエスト失敗時に再試行するようにする | QUARTETCOM TECH BLOG

指数バックオフアルゴリズム (Exponential Backoff Algorithm)とは

Symfonyのretry_failed optionsの設定方法

本当に指数関数的にリトライしているか検証

1. HTTP 429エラー(2リクエスト/10秒)を意図的に発生させるAPIを作成

2. 1で作成したAPIを使用するクライアントにSymfonyのretry_failedオプションを設定

3. リトライ処理が実際に行われているか確認

まとめ

PHPでGraphQLサーバー構築入門：Symfony＋API Platformを活用した実践 | QUARTETCOM TECH BLOG

✅️ 今回作成するもの

📝 目次

1. Symfonyプロジェクトのセットアップ

2. API Platformの導入

3. データベース接続（PostgreSQL）

4. Book / Reviewエンティティの作成とマイグレーション

5. データ登録 (REST API)

6. GraphQLの有効化

7. GraphQLで書籍一覧を取得

8. カスタムフィールド（レビューの平均スコア）を追加

📌 Bookエンティティに集計ロジックを追加

📌 GraphQLでフィールドを有効化する

9. フロント側からデータを取得する

GraphQLクエリの定義

コンポーネント側の実装

10. まとめ

📚️ 参考リンク

Angularリアクティブフォームの型安全な使い方 ─ 罠を避ける実践ポイント | QUARTETCOM TECH BLOG

はじめに

Angularのフォーム構成の方法

リアクティブフォームの構成要素

フォームオブジェクトの生成方法

2. 初期設定: `/init` と `CLAUDE.md`

プロジェクトの「記憶」を作る `/init`

3. うまく伝わらない時は？コンテキスト管理のコツ

基本は `/clear` でリセット

コンテキストを残したいなら `/compact`