概要

多言語対応は一般的に翻訳関数に翻訳キーを渡すことで実装されます。その際に問題になるのが、キー名の間違い、キー名の変更漏れなどによる実装不備です。このようなエラーを人の目で全て確認するのは難しいため、システムによる検知が有効です。

この記事では、TypeScriptの型システムを活用した、型チェックの方法を説明します。これにより、正しい翻訳キーが割り当てられていることがコンパイル時にチェックされ、アプリケーションの品質向上に大きな効果が期待できます。

多言語システムの実装

1. ベースとなる型の定義

翻訳の型チェックは、日本語のメッセージファイル（ja.ts）をベースとして構築します。翻訳ファイルはJSONファイルで扱われることもありますが、型チェックという観点ではtsファイルで管理するのがおすすめです。

1
2
3

import { jaMessage } from './ja'

export type JaMessage = typeof jaMessage

TypeScriptの機能：typeof演算子

typeof演算子は、値から型を抽出するTypeScriptの機能です。typeof jaMessageにより、jaMessageオブジェクトの構造から型を自動的に生成します。これにより、jaMessageの構造が変更されると、型定義も自動的に更新されます。

ja.tsのサンプルコード

以下は、日本語メッセージファイル（ja.ts）のサンプルです。このファイルが型定義のベースとなります。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

export const jaMessage = {
  term: {
    next: '次へ',
    back: '戻る',
    cancel: 'キャンセル',
    submit: '送信',
  },
  pages: {
    home: {
      title: 'ホーム',
    },
    about: {
      title: '紹介',
    },
    contact: {
      title: 'お問い合わせ',
    },
    terms: {
      title: '利用規約',
    },
  },
} as const

このファイルでは、as constを使用することで、値がリテラル型として推論されます。これにより、型の精度が向上し、より厳密な型チェックが可能になります。

as constとは

as constは、TypeScriptの「constアサーション」という機能です。オブジェクトや配列にas constを付けることで、以下の効果が得られます。

1. リテラル型として推論される: 値が具体的なリテラル型（例：'マイページ'）として推論されます
2. 読み取り専用になる: オブジェクトのプロパティがreadonlyになります
3. 型の精度が向上する: より具体的な型情報が保持されます

as constがない場合

as constがない場合、TypeScriptは値の型を一般的な型として推論します。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// as const がない場合
export const jaMessage = {
  term: {
    next: '次へ',
    back: '戻る',
  },
}

// 推論される型
// {
//   term: {
//     next: string;  // 一般的な string 型
//     back: string;  // 一般的な string 型
//   }
// }

この場合、typeof jaMessageで取得できる型は、値がstring型として推論されます。

as constがある場合

as constがある場合、TypeScriptは値の型をリテラル型として推論します。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// as const がある場合
export const jaMessage = {
  term: {
    next: '次へ',
    back: '戻る',
  },
} as const

// 推論される型
// {
//   readonly term: {
//     readonly next: '次へ';         // リテラル型
//     readonly back: '戻る';         // リテラル型
//   }
// }

この場合、typeof jaMessageで取得できる型は、値が具体的なリテラル型（'次へ'、'戻る'）として推論されます。

なぜas constが必要なのか

翻訳メッセージの型チェックにおいて、as constは以下の理由で重要です。

1. 型の一貫性: typeof jaMessageで取得した型が、実際の値の構造を正確に反映します
2. 型の精度: GenericTypeが適用される際、元の構造が正確に保持されます
3. 読み取り専用の保証: 翻訳メッセージが誤って変更されることを防ぎます

実際の違い

as constの有無による型の違いを確認してみましょう。

1
2
3
4
5
6
7
8
9

// as const がない場合
const message1 = { term: { next: '次へ' } }
type Type1 = typeof message1
// Type1 = { term: { next: string } }

// as const がある場合
const message2 = { term: { next: '次へ' } } as const
type Type2 = typeof message2
// Type2 = { readonly term: { readonly next: '次へ' } }

as constがある場合、nextの型は'次へ'という具体的なリテラル型になります。これにより、型システムがより正確に動作し、翻訳キーの型チェックがより厳密になります。

2. 再帰的な型変換

翻訳メッセージはネストされたオブジェクト構造を持っています。この構造を型として表現するために、GenericTypeというユーティリティ型を使用しています。

1
2
3
4
5

type GenericType<T extends object> = {
  [K in keyof T]: T[K] extends object ? GenericType<T[K]> : string
}

export type I18nMessage = GenericType<JaMessage>

TypeScriptの機能：条件型（Conditional Types）と再帰的な型

• [K in keyof T]: マップ型（Mapped Types）により、オブジェクトの各キーを反復処理します

• T[K] extends object ? GenericType<T[K]> : string: 条件型により、値がオブジェクトの場合は再帰的にGenericTypeを適用し、そうでない場合はstring型とします

これにより、以下のような構造が正しく型付けされます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  term: {
    next: string  // 文字列型
    back: string
    cancel: string
    submit: string
  },
  pages: {
    home: {
      title: string  // 3段階のネストも正しく型付けされる
    },
    about: {
      title: string
    },
    contact: {
      title: string
    },
    terms: {
      title: string
    }
  }
}

GenericTypeは再帰的に動作するため、何段階のネストでも正しく型付けされます。

3. 各言語ファイルでの型チェック

各言語ファイルでは、I18nMessage型を明示的に指定することで、型チェックが行われます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

import { I18nMessage } from './types'

export const enMessage: I18nMessage = {
  term: {
    next: 'Next',
    back: 'Back',
    cancel: 'Cancel',
    submit: 'Submit',
  },
  pages: {
    home: {
      title: 'Home',
    },
    about: {
      title: 'About',
    },
    contact: {
      title: 'Contact',
    },
    terms: {
      title: 'Terms',
    },
  },
}

型チェックの効果

• 必須キーが欠落している場合、コンパイルエラーが発生します

• 存在しないキーを追加しようとすると、エラーが発生します

• 値の型がstringでない場合、エラーが発生します

• キーのタイポがある場合、エラーが発生します

4. 翻訳関数の型安全な実装

翻訳関数はライブラリを利用してもよいですが、シンプルな翻訳システムであれば自前で実装するのもよいと思います。ここでは、必要最低限の翻訳関数のサンプルを紹介します。

翻訳関数についても型安全を担保する必要があります。型システムを実装するために、Paths型とPathValue型を使用します。

キーパスの型生成

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

type PathsInternal<T> = T extends string
  ? never
  : T extends object
  ? {
      [K in keyof T]: K extends string
        ? T[K] extends object
          ? T[K] extends string
            ? K
            : `${K}.${PathsInternal<T[K]>}`
          : K
        : never
    }[keyof T]
  : never

export type Paths = PathsInternal<JaMessage>

この型により、'term.next'、'pages.home.title'のような文字列リテラル型が自動生成されます。

キーパスから値を取得する型

1
2
3
4
5
6
7
8
9
10
11

export type PathValue<T, P extends string> = P extends `${infer Key}.${infer Rest}`
  ? Key extends keyof T
    ? T[Key] extends object
      ? PathValue<T[Key], Rest>
      : never
    : never
  : P extends keyof T
  ? T[P] extends string
    ? T[P]
    : never
  : never

この型により、キーパスから対応する文字列型を取得できます。

翻訳関数の実装

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

import { I18nMessage, Paths, PathValue } from './types'

export type I18nFunction = <P extends Paths>(
  key: P
) => PathValue<I18nMessage, P>

export function createI18n(message: I18nMessage): I18nFunction {
  return function <P extends Paths>(key: P & string): PathValue<I18nMessage, P> {
    const keys = (key as string).split('.')
    let value: any = message

    for (const k of keys) {
      if (value && typeof value === 'object' && k in value) {
        value = value[k as keyof typeof value]
      } else {
        throw new Error(`Translation key "${key}" not found`)
      }
    }

    if (typeof value !== 'string') {
      throw new Error(`Translation key "${key}" does not point to a string value`)
    }

    return value as PathValue<I18nMessage, P>
  }
}

使用例

翻訳関数の使用例です。

翻訳関数の使用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

import { createI18n } from './i18n'
import { jaMessage } from './ja'
import { enMessage } from './en'

// 日本語の翻訳関数を作成
const tJa = createI18n(jaMessage)

// 英語の翻訳関数を作成
const tEn = createI18n(enMessage)

// 使用例
console.log(tJa('term.next')) // '次へ'
console.log(tJa('pages.home.title')) // 'ホーム'
console.log(tJa('pages.about.title')) // '紹介'
console.log(tJa('pages.contact.title')) // 'お問い合わせ'
console.log(tJa('pages.terms.title')) // '利用規約'

console.log(tEn('term.next')) // 'Next'
console.log(tEn('pages.home.title')) // 'Home'
console.log(tEn('pages.about.title')) // 'About'
console.log(tEn('pages.contact.title')) // 'Contact'
console.log(tEn('pages.terms.title')) // 'Terms'

正しい使用例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

export const enMessage: I18nMessage = {
  term: {
    next: 'Next', // ✅ 正しい
    back: 'Back',
    cancel: 'Cancel',
    submit: 'Submit',
  },
  pages: {
    home: {
      title: 'Home',  // ✅ 3段階のネストも正しい
    },
    about: {
      title: 'About',
    },
    contact: {
      title: 'Contact',
    },
    terms: {
      title: 'Terms',
    },
  },
}

エラーが発生する例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

export const enMessage: I18nMessage = {
  term: {
    next: 'Next',
    // ❌ エラー: 'back' プロパティが必須だが欠落している
  },
}

// ❌ エラー: 'unknownKey' は存在しないキー
export const enMessage: I18nMessage = {
  term: {
    next: 'Next',
    unknownKey: 'Value',  // エラー
  },
}

// ❌ エラー: 翻訳関数で存在しないキーを指定
const t = createI18n(enMessage)
t('term.invalidKey')      // コンパイルエラー
t('pages.home.invalid')   // コンパイルエラー
t('invalid.path')         // コンパイルエラー
t('pages.invalid.title')  // コンパイルエラー

メリット

1. コンパイル時の安全性: 翻訳キーのエラーを実行前に検出できます

2. 自動補完: IDEが翻訳キーを自動補完してくれます

3. リファクタリングの安全性: キー名を変更する際、使用箇所を自動的に検出できます

4. ドキュメントとしての役割: 型定義自体が、利用可能な翻訳キーのドキュメントとなります

5. 翻訳関数の型安全: 翻訳関数を使用する際も、存在しないキーを指定するとコンパイルエラーが発生します

サンプルコード

サンプルコードは https://github.com/shoyan/i18n-sample で公開しています。

はじめに

Goを書いていると、以下のようなコードを見かけることがあります。

1

var _ Interface = (*Type)(nil)

この一見奇妙なコードは、Goのインターフェース実装をコンパイル時にチェックするためのイディオムです。今回は、このイディオムの目的、必要性、そして適切な使用場面について詳しく解説します。

このイディオムの目的

基本的な仕組み

もう少し具体的なコードで説明してみます。以下のコードは、Counterインターフェースを実装していることをチェックするイディオムです。

1

var _ Counter = (*CountRepository)(nil)

このコードは以下の要素で構成されています：

• var _ : 空白識別子（blank identifier）を使用した変数宣言
• Counter : チェック対象のインターフェース
• (*CountRepository)(nil) : チェック対象の型（nilポインタ）

何をしているのか

このイディオムは、*CountRepository 型が Counter インターフェースを実装しているかをコンパイル時にチェックします。

実際の動作例

正常な場合

以下のコードは Counter インターフェースを実装したサンプルコードです。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

package main

import (
	"context"
	"fmt"
)

type Counter interface {
    Increment(ctx context.Context, key string) (int, error)
    Get(ctx context.Context, key string) (int, error)
    Reset(ctx context.Context, key string) error
}

type CountRepository struct {
}

// すべてのメソッドを実装
func (r *CountRepository) Increment(ctx context.Context, key string) (int, error) {
    // 実装
    return 0, nil
}

func (r *CountRepository) Get(ctx context.Context, key string) (int, error) {
    // 実装
    return 0, nil
}

func (r *CountRepository) Reset(ctx context.Context, key string) error {
    // 実装
    return nil
}

// インターフェース実装チェック
var _ Counter = (*CountRepository)(nil)

func main() {
    // インターフェース実装チェックのサンプル
    repo := &CountRepository{}
    ctx := context.Background()
    
    // メソッド呼び出し
    count, _ := repo.Increment(ctx, "test")
    fmt.Printf("Count: %d\n", count)
}

CountRepositoryはCounterインターフェースで定義してある、Inctement、Get、Resetが実装してあるため、ビルドコマンドでビルドすることができます。

1

go build sample.go

エラーの場合

エラーを発生させるために、Counter インターフェースにDecrementを追加してみましょう。

1
2
3
4
5
6

type Counter interface {
    Increment(ctx context.Context, key string) (int, error)
    Get(ctx context.Context, key string) (int, error)
    Reset(ctx context.Context, key string) error
    Decrement(ctx context.Context, key string) (int, error)
}

ビルドすると、ビルドエラーが発生します。インターフェースの未実装が検知されていますね。

コンパイルエラーメッセージ：

1

./sample.go:35:17: cannot use (*CountRepository)(nil) (value of type *CountRepository) as Counter value in variable declaration: *CountRepository does not implement Counter (missing method Decrement)

では、イディオムをコメントアウトしてみるとどうでしょうか。

1
2

// インターフェース実装チェック
// var _ Counter = (*CountRepository)(nil)

ビルドすると、エラーが発生しなくなりました。これは、コンパイル時にインターフェースの未実装が検知されていないことを意味しています。

なぜこのイディオムが必要なのか

このイディオムですが、通常は不要な場合がほとんどです。
例えば、以下のように NewCounter 関数を追加して、CountRepository は Counter インターフェースであるということを明示的に指定した場合、GOのコンパイラでインターフェースの実装を検知することができます。

1
2
3
4
5
6
7

type CountRepository struct {
}

// Counterインターフェースという型が明示されている
func NewCounter() Counter {
    return &CountRepository{}
}

エフェクティブGoの指針

エフェクティブGoでは、このイディオムについて以下のように述べています。

The appearance of the blank identifier in this construct indicates that the declaration exists only for the type checking, not to create a variable. Don’t do this for every type that satisfies an interface, though. By convention, such declarations are only used when there are no static conversions already present in the code, which is a rare event.

重要なポイント

1. 空白識別子の役割 : 変数を作成せず、型チェックのみを目的とする
2. 乱用すべきではない : すべてのインターフェース実装に使うべきではない
3. 静的変換がない場合のみ : 既に型チェックの機会がある場合は不要

使いどころは、静的変換がない場面 です。

静的変換とは

静的変換（static conversion） とは、コンパイル時に型の互換性をチェックする機会のことです。

静的変換がある場合（イディオムは不要）

1
2
3
4
5
6
7
8
9

func Process(repo Counter) {  // ← 静的変換が発生
    // 処理
}

func main() {
    r := &CountRepository{}
    Process(r)  // ← ここで型チェックが行われる
    // そのため、var _ は不要
}

静的変換がない場合（イディオムが有用）

1
2
3
4
5
6
7

// インターフェースと実装が分離されていて、
// まだ使用箇所がない場合
type CountRepository struct{}

// この時点では静的変換が発生していない
// そのため、明示的に型チェックを行う
var _ Counter = (*CountRepository)(nil)

適切な使用場面

1. リポジトリパターン

1
2
3
4
5
6
7
8
9
10
11
12
13

// domain/repository/user.go
type UserRepository interface {
    Get(ctx context.Context, id string) (*User, error)
    Create(ctx context.Context, user *User) error
}

// infrastructure/repository/user.go
type UserRepository struct {
    db *gorm.DB
}

// リポジトリパターンでは、インターフェースと実装が分離されているため有用
var _ repository.UserRepository = (*UserRepository)(nil)

2. プラグインアーキテクチャ

1
2
3
4
5
6
7
8
9
10
11

// plugin/interface.go
type Plugin interface {
    Initialize() error
    Execute() error
}

// plugin/example.go
type ExamplePlugin struct{}

// プラグインが正しくインターフェースを実装しているかをチェック
var _ Plugin = (*ExamplePlugin)(nil)

不適切な使用例

既に静的変換がある場合

既に静的変換がある場合はイディオムは必要ありません。

1
2
3
4
5
6
7

// 既に使用箇所がある場合
func NewUserService(repo UserRepository) *UserService {
    return &UserService{repo: repo}
}

// この場合、NewUserServiceの呼び出し時に既に型チェックが行われるため
// var _ は不要

まとめ

var _ Interface = (*Type)(nil) イディオムは 静的変換がない場合のみ 使用すればOKです。

コードの品質を測る指標として「複雑度」がありますが、特に循環的複雑度（Cyclomatic Complexity）は、コードの保守性やバグの発生リスクを定量的に評価できる指標です。

この記事では、循環的複雑度の計算方法、複雑度を削減する方法、実践的な測定ツールについて、詳しく解説していきます。

循環的複雑度（Cyclomatic Complexity）とは

循環的複雑度は、プログラムの制御フローの分岐の数から算出される複雑度の指標です。この値が高いほど、コードは複雑で理解しにくく、バグが発生しやすくなります。

基本計算式

1

M = E - N + 2P

• M: 循環的複雑度
• E: 制御フローグラフの辺の数（edge）
• N: 制御フローグラフのノード数（node）
• P: 連結成分の数（通常は1で計算する）

簡易計算方法（現場でよく使われる）

実際の開発現場では、以下の簡易計算方法がよく使われます。

1. if、for、while、case、catch などの分岐やループの数を数える
2. その数に 1 を足す

計算例で理解する循環的複雑度

簡単な関数を例に説明をしていきます。

例1：簡易計算方法

まずは、簡易的な計算方法で関数の複雑度を計算していきましょう。

1
2
3
4
5
6
7
8
9
10
11
12
13

function example(x) {
  if (x > 0) {           // 分岐 1
    console.log("A");
  } else if (x === 0) {  // 分岐 2
    console.log("B");
  } else {
    console.log("C");
  }

  for (let i = 0; i < 5; i++) {  // 分岐 3
    console.log(i);
  }
}

• 分岐・ループの数：3
• 複雑度：3 + 1 = 4

上記の例のように分岐を繰り返しを数えて+1をすれば概算で計算することができます。

例2：基本計算式を使った計算方法

次は M = E - N + 2P を使った計算方法を見ていきましょう。

1
2
3

function helper() {
  console.log("do something");
}

制御フローグラフ：
まずは、関数の制御フローグラフを作成します。

1

[Start] → [print] → [End]

計算：
次に制御フローグラフからノードの数、辺の数を数えます。

• N（ノード数）= 3（Start, print, End）
• E（辺の数）= 2（Start→print, print→End）
• P（連結成分数）= 1

1
2
3

M = E - N + 2P
M = 2 - 3 + 2*1
M = 1

結果：複雑度 = 1（最低値、まったく複雑ではない関数）

分岐を追加した場合

次に分岐を追加した関数の計算をしてみましょう。

1
2
3
4
5

function helper(flag) {
  if (flag) {
    console.log("do something");
  }
}

制御フローグラフ：

1
2

[Start] → (flag?) ─Yes→ [print] → [End]
               └─No──────────────→ [End]

計算：

• N（ノード数）= 4（Start, 条件判定, print, End）
• E（辺の数）= 4（Start→条件判定, 条件判定→print, 条件判定→End, print→End）
• P（連結成分数）= 1

1
2
3

M = E - N + 2P
M = 4 - 4 + 2*1
M = 2

結果：複雑度 = 2（分岐を1つ追加しただけで、複雑度は 1 → 2 に増加）

ネストした条件分岐

条件分岐がネストした関数の循環的複雑度を計算をしてみます。

1
2
3
4
5
6
7

function helper(a, b) {
  if (a > 0) {
    if (b > 0) {
      console.log("A and B are positive");
    }
  }
}

制御フローグラフ：

1
2
3
4
5
6
7
8
9
10
11

[Start] 
   |
(a > 0?) ----No----> [End]
   |
  Yes
   |
(b > 0?) ----No----> [End]
   |
  Yes
   |
[print] → [End]

計算：

• N（ノード数）= 5（Start, 条件判定1, 条件判定2, print, End）
• E（辺の数）= 6（Start→条件判定1, 条件判定1→End, 条件判定1→条件判定2, 条件判定2→End, 条件判定2→print, print→End）
• P（連結成分数）= 1

1
2
3

M = E - N + 2P
M = 6 - 5 + 2*1
M = 3

結果：複雑度 = 3

重要なポイント

• 循環的複雑度は「ネストの深さ」ではなく「分岐の総数」で増える
• ただし、ネストが深いと認知的複雑度（Cognitive Complexity）はもっと増える
• 人間はネスト構造を理解するのが苦手なので、Cognitive Complexity では深さもペナルティになる

複雑度の目安

関数呼び出しと複雑度の関係

循環的複雑度の計算は、原則として「関数ごとに独立して」計測するのが基本です。

基本ルール

• 呼び出している関数の中身はカウントに含めない
• 関数呼び出しは、それ自体は「分岐」でも「ループ」でもないので複雑度には直接影響しない
• 複雑度に影響するのは、その関数呼び出しが条件式の一部やループの制御として使われている場合

例1：単純な呼び出し（複雑度に影響なし）

1
2
3
4
5
6
7

function helper() {
  console.log("do something");
}

function main() {
  helper();
}

• main の中には分岐もループもなし
• main の複雑度 = 1（最低値）
• helper は別に計算（=1）

例2：条件式の中で呼び出し（影響あり）

1
2
3
4
5
6
7
8
9

function isValid(x) {
  return x > 0;
}

function main(x) {
  if (isValid(x)) {   // 分岐1
    console.log("ok");
  }
}

• isValid() の中身はカウントしないが、if の分岐1つとして main の複雑度に加算される
• 複雑度：
  • main = 1（if）+ 1 = 2
  • isValid = 1

複雑度を下げる方法

1. 関数の分割

関数を分割することで１つ１つの関数の循環的複雑度は下がります。

Before（複雑度 = 8）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

function complexFunction(data) {
  if (data.type === 'A') {
    // 処理A
    if (data.value > 10) {
      // 処理A-1
    } else {
      // 処理A-2
    }
  } else if (data.type === 'B') {
    // 処理B
    if (data.value > 20) {
      // 処理B-1
    } else {
      // 処理B-2
    }
  }
}

After（複雑度 = 2）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

function processTypeA(data) {
  if (data.value > 10) {
    // 処理A-1
  } else {
    // 処理A-2
  }
}

function processTypeB(data) {
  if (data.value > 20) {
    // 処理B-1
  } else {
    // 処理B-2
  }
}

function complexFunction(data) {
  if (data.type === 'A') {
    return processTypeA(data);
  } else if (data.type === 'B') {
    return processTypeB(data);
  }
}

2. ポリモーフィズムの活用

ポリモーフィズムを使うことで、分岐がなくなります。それにより、複雑度が下がります。
Before（複雑度 = 6）

1
2
3
4
5
6
7
8
9

function processPayment(payment) {
  if (payment.type === 'credit') {
    return processCreditCard(payment);
  } else if (payment.type === 'debit') {
    return processDebitCard(payment);
  } else if (payment.type === 'bank') {
    return processBankTransfer(payment);
  }
}

After（複雑度 = 1）：

1
2
3
4
5
6
7
8
9
10

const paymentProcessors = {
  credit: processCreditCard,
  debit: processDebitCard,
  bank: processBankTransfer
};

function processPayment(payment) {
  const processor = paymentProcessors[payment.type];
  return processor ? processor(payment) : throw new Error('Unknown payment type');
}

測定ツール

ここでは、循環的複雑度の計算方法について説明してきました。
実際の関数は複雑であり、手計算は現実的ではありません。各言語でツールが開発されており、そのツールを利用するのがよいです。

• JavaScript/TypeScript: ESLint
• Python: radon
• Java: SonarQube / PMD
• Go: gocyclo

まとめ

循環的複雑度は、コードの品質を数値で測れる指標です。チーム開発では「このコードは複雑すぎる」という主観的な意見ではなく、「複雑度が15だからリファクタリングが必要」と客観的に判断できます。複雑度の計算方法を理解すれば、コードレビューでも「なぜこの関数は複雑なのか」を論理的に説明できるようになり、より建設的な議論ができるようになります。

HTTP中継（プロキシ）は、アプリケーション層（OSIの第7層）のHTTPプロトコルを中継（再発行）する仕組みです。プロキシサーバーはTCP/IPのセッションを一度終了させ、新たに別のセッションを開始して通信を中継します。

この記事では、HTTPの構造、リクエスト/レスポンスの伝播、TCP/IP層での扱い、ヘッダーの処理など、「プロトコルとして何がどう動いているか」に焦点を当てて詳述します。

HTTP中継のプロトコル的な概要

HTTP中継（proxy）は、アプリケーション層（OSIの第7層）のHTTPプロトコルを中継（再発行）するものです。プロキシサーバーはTCP/IPのセッションを一度終了させ、新たに別のセッションを開始して通信を中継します。

1

[Client] --(HTTP over TCP)--> [Proxy] --(HTTP over TCP)--> [Server]

つまり、ClientとProxy間のTCPコネクションと、ProxyとServer間のTCPコネクションは完全に別物です。

プロトコル単位での構造

1. クライアント→プロキシ（Proxy）

クライアントからプロキシへのHTTPリクエスト例

1
2
3
4
5

GET /api/item HTTP/1.1
Host: proxy.example.com
Content-Type: application/json
Content-Length: 12345
Authorization: Bearer token123

2. プロキシでの動作

プロキシサーバーは以下を行います。

• TCPで受け取ったHTTPリクエストをアプリケーション層で解析
• 必要に応じてヘッダーを書き換え（例：Host, Authorization, X-Forwarded-For など）
• 新たなHTTPリクエストとしてバックエンドに送信

3. プロキシ→バックエンド

プロキシからバックエンドで新たなリクエストが送られます。
リクエスト先Hostがbackendサーバーに変更され、X-Forwarded-Forが追加、Authorizationがプロキシによって変更されています。

1
2
3
4
5
6

GET /api/item HTTP/1.1
Host: backend.internal
Content-Type: application/json
Content-Length: 12345
X-Forwarded-For: 192.168.1.10
Authorization: internal-api-key

4. バックエンド→プロキシ（HTTPレスポンス）

バックエンドサーバーはプロキシにレスポンスを返します。

1
2
3
4
5

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 123

{"username": "taro"}

5. プロキシ→クライアント

そのレスポンスを、必要に応じて加工しながら、もとのクライアントに返します。

TCP/IPレイヤーの流れ

ヘッダーの役割とプロキシにおける重要性

プロキシの種類と特徴

フォワードプロキシ

クライアントがプロキシを経由してインターネットにアクセスする形態です。

1

[Client] → [Forward Proxy] → [Internet] → [Server]

リバースプロキシ

サーバーの前に配置され、クライアントからのリクエストを適切なバックエンドサーバーに振り分ける形態です。

1

[Client] → [Reverse Proxy] → [Backend Server]

トランスペアレントプロキシ

クライアントがプロキシの存在を意識せずに通信できるプロキシです。通常はネットワークレベルでトラフィックをインターセプトします。

プロキシにおける重要な技術的考慮事項

1. コネクション管理

プロキシは以下のコネクション管理が重要です。

• Keep-Alive: クライアントとのコネクションを維持
• Connection Pooling: バックエンドサーバーとのコネクションを再利用
• タイムアウト設定: 適切なタイムアウト値の設定

2. バッファリングとストリーミング

• メモリ使用量の最適化: 大きなファイルやデータを扱う場合、バッファリングとストリーミングでメモリ使用量を最小限に抑えることが重要です

3. エラーハンドリング

プロキシは様々なエラーケースを適切に処理する必要があります。

• バックエンドサーバーの障害
• ネットワークタイムアウト
• 不正なHTTPリクエスト
• SSL/TLS証明書の問題

まとめ

HTTP中継（プロキシ）は、単純に見えて実は非常に複雑な仕組みです。TCP/IPレイヤーでのセッション管理、HTTPヘッダーの適切な処理、セキュリティ上の考慮事項など、多くの技術的要素が絡み合っています。

この記事で解説した内容を基に、実際のプロキシサーバーの設定や、カスタムプロキシの実装に取り組んでみてください。

GraphQLでファイルアップロードを実装する場合、いくつかの方法があります。GraphQL自体はバイナリデータを直接扱う仕様にはなっていませんが、工夫次第で実現可能です。

この記事では、GraphQLでのファイルアップロード実装について詳しく解説し、適切な方法を選択できるようにします。

バイナリデータの取り扱いについて

GraphQLの標準プロトコルはJSONのみをサポートしており、JSONはバイナリデータを直接扱えません。しかし、工夫次第でバイナリデータの送受信は可能です。主な方法は以下の2つです。

1. Base64エンコードで送信

• バイナリデータをBase64文字列に変換し、GraphQLのString型で送受信します
• 小さなファイルや簡易的な用途には使えますが、ファイルサイズが大きいと効率が悪くなります

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// クライアント側
const file = document.getElementById('fileInput').files[0];
const reader = new FileReader();
reader.onload = function() {
  const base64 = reader.result.split(',')[1]; // data:image/jpeg;base64, の部分を除去
  
  const mutation = `
    mutation UploadFile($file: String!) {
      uploadFile(file: $file) {
        id
        url
        filename
      }
    }
  `;
  
  // GraphQLリクエストを送信
  fetch('/graphql', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query: mutation,
      variables: { file: base64 }
    })
  });
};
reader.readAsDataURL(file);

2. GraphQL multipart request specification（ファイルアップロード）

• Apollo Serverやgraphql-uploadなどのライブラリを使うことで、multipart/form-data形式でファイルアップロードが可能です
• これはHTTPの拡張で、GraphQLのmutationと一緒にバイナリファイルを送信できます
• サーバー側でgraphql-uploadなどのミドルウェアが必要です

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// クライアント側
const file = document.getElementById('fileInput').files[0];
const formData = new FormData();

formData.append('operations', JSON.stringify({
  query: `
    mutation UploadFile($file: Upload!) {
      uploadFile(file: $file) {
        id
        url
        filename
      }
    }
  `,
  variables: { file: null }
}));

formData.append('map', JSON.stringify({
  "0": ["variables.file"]
}));

formData.append('0', file);

fetch('/graphql', {
  method: 'POST',
  body: formData
});

multipart/form-dataとは

multipart/form-dataは、HTTPリクエストでテキストデータとバイナリデータ（ファイル）を同時に送信するためのMIMEタイプです。HTMLの<form>要素でファイルアップロードを行う際に使用されます。

基本的な構造

1. Content-Typeヘッダー

1

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

• boundaryは、データの境界を区切る文字列です
• ブラウザやクライアントが自動生成します

2. リクエストボディの構造

1
2
3
4
5
6
7
8
9
10

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="text_field"

Hello World
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="image.jpg"
Content-Type: image/jpeg

[バイナリデータ]
------WebKitFormBoundary7MA4YWxkTrZu0gW--

3. 実際のHTTPリクエスト例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

POST /graphql HTTP/1.1
Host: api.example.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="operations"

{"query":"mutation UploadFile($file: Upload!) { uploadFile(file: $file) { id url filename } }","variables":{"file":null}}
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="map"

{"0":["variables.file"]}
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="0"; filename="document.pdf"
Content-Type: application/pdf

[PDFファイルのバイナリデータ]
------WebKitFormBoundary7MA4YWxkTrZu0gW--

4. GraphQL multipart request specificationの構造

1. operations: GraphQLクエリのJSON
2. map: ファイルとGraphQL変数のマッピング
3. 0, 1, 2…: 実際のファイルデータ

Base64エンコードとバイナリの比較

セキュリティ

ファイルアップロード処理における、基本的なセキュリティ対策を紹介します。

1. ファイルサイズの制限

サーバー側でファイルサイズを検証します。

2. ファイルタイプの検証

ホワイトリスト方式で .jpg, .png, .pdf のように明示的に許可された拡張子のみ受付します。
また、クライアントから送られたContent-Typeではなく、サーバー側でMIMEタイプを再検査します。

3. ファイル名のリネーム

アップロードされたファイルをランダム名に変えて保存（例：upload_48cd1e2a.jpg）します。

まとめ

GraphQLでのファイルアップロードは、Base64エンコード方式とmultipart/form-data方式の2つのアプローチがあります。

• Base64エンコード: 小さなファイルや簡易的な用途に適している
• multipart/form-data: 大きなファイルや本格的なファイルアップロード機能に適している

用途に応じて適切な方法を選択し、ファイルサイズ制限やファイルタイプ検証などのセキュリティ対策も忘れずに実装することが重要です。