画像API on 設計書

署名付きURL 発行

Mon, 01 Jan 0001 00:00:00 +0000

署名付きURL 発行#

ID#

api001-upload

エンドポイント#

メソッド	パス
POST	`/images/presigned-url`

概要#

S3アップロード用の署名付きURLを発行する。

リクエスト#

ボディ#

物理名	論理名	型	必須	説明
fileName	ファイル名	string	✓	アップロードするファイル名
fileSize	ファイルサイズ	number	✓	ファイルサイズ（バイト単位）
contentType	Content-Type	string	✓	MIMEタイプ

{
 "fileName": "string",
 "fileSize": "number",
 "contentType": "string"
}

バリデーション#

検証項目	条件	レスポンス	メッセージ	備考
ファイルサイズ	5MB 超	`400 Bad Request`	MSG-API-001
Content-Type	許可リスト外	`400 Bad Request`	MSG-API-002	許可 Content-Type: `image/jpeg` `image/png` `image/gif` `image/webp`
アップロード枚数上限	同一ユーザーが 5 枚以上保持	`409 Conflict`	MSG-API-003
レート制限	同一 IP から 1 分間に 10 回超	`429 Too Many Requests`	MSG-API-C001	共通仕様に準拠

Presigned URL 有効期限#

発行から 300 秒（5 分） 以内に PUT が完了しない場合 URL は無効となる。期限切れ時はクライアントが発行から再試行する。

アップロード完了・メタデータ登録

Mon, 01 Jan 0001 00:00:00 +0000

アップロード完了・メタデータ登録#

ID#

api002-upload

エンドポイント#

メソッド	パス
POST	`/images`

概要#

S3への直接アップロード完了後、マジックナンバー検証を行いメタデータをDBに登録する。

リクエスト#

ボディ#

物理名	論理名	型	必須	説明
key	S3オブジェクトキー	string	✓	S3上の保存パス

{
 "key": "string"
}

バリデーション#

検証項目	条件	レスポンス	メッセージ	備考
S3ファイル存在	ファイルが存在しない	`404 Not Found`	MSG-API-005
マジックナンバー	許可フォーマット外	`422 Unprocessable Entity`	MSG-API-004	S3ファイルを削除（失敗時422）
S3削除失敗	削除操作のエラー	`500 Internal Server Error`	MSG-API-006	トランザクション不整合リスク
アップロード枚数上限	排他ロック取得後に5件以上	`409 Conflict`	MSG-API-003	SELECT FOR UPDATEで競合防止後にチェック

マジックナンバー検証#

S3上のファイルの先頭バイト列を読み取り、実際のMIMEタイプを検証する。ファイルサイズはS3 HeadObjectメタデータから取得し、クライアント送信値に依存しない。

フォーマット	マジックナンバー
JPEG	`FF D8 FF`
PNG	`89 50 4E 47 0D 0A 1A 0A`
GIF	`47 49 46 38`
WebP	`52 49 46 46` (offset 0) + `57 45 42 50` (offset 8)

レスポンス#

201 Created#

物理名	論理名	型	必須	説明
id	画像ID	string	✓	登録された画像のID
url	閲覧用URL	string	✓	画像の閲覧用URL

{
 "id": "string",
 "url": "string"
}

ステータスコード#

コード	説明
201	成功
404	S3上にファイルが存在しない
409	アップロード枚数上限超過（5件以上）
422	マジックナンバー検証失敗（S3ファイルを削除）
500	S3削除失敗またはDB登録失敗

内部処理シーケンス#

sequenceDiagram
 autonumber
 actor User
 participant Hono as Hono Middleware
 participant Domain as Domain Service
 participant S3 as S3 Client
 participant DB as Repository

 User->>+Hono: 完了通知 (key, request_id, trace_id )
 Hono->>Domain: 完了通知 (key, request_id, trace_id)
 Domain->>+S3: HeadObject（ファイルの存在確認・メタデータ取得）
 S3-->>-Domain: metadata (fileSize, ContentType, ...)
 Domain->>+S3: GetObject（先頭バイト取得）
 S3-->>-Domain: fileBytes
 Domain->>Domain: マジックナンバー検証
 alt 検証失敗
 Domain->>+S3: DeleteObject
 S3-->>-Domain: result
 Domain-->>Hono: Error (422 Unprocessable Entity)
 else 検証成功
 Domain->>+DB: SELECT FOR UPDATE（排他ロック取得 + 件数確認）
 DB-->>-Domain: currentCount
 alt 5件以上
 Domain-->>Hono: Error (409 Conflict)
 else 5件未満
 Domain->>+DB: INSERT メタデータ (id, key, fileSize, contentType, ...)
 DB-->>-Domain: result
 alt DB保存成功
 Domain-->>Hono: Success (201, id, url)
 else DB保存失敗
 Domain-->>Hono: Error (500 Internal Server Error)
 end
 end
 end
 Hono-->>-User: Response

懸案事項#

S3とDB間の分散トランザクション#

現状:

画像一覧取得

Mon, 01 Jan 0001 00:00:00 +0000

画像一覧取得#

ID#

api003-upload

エンドポイント#

メソッド	パス
GET	`/images`

概要#

アップロード済み画像のメタデータ一覧（ID・ファイル名）を取得する。画像の実体（バイナリ・閲覧用URL）はここでは取得しない。ユーザーがリストから画像を選択した時点で api004-upload により個別取得する。

レスポンス#

200 OK#

物理名	論理名	型	必須	説明
id	画像ID	string	✓	登録された画像のID
fileName	ファイル名	string	✓	アップロードされたファイル名
createdAt	作成日時	string	✓	ISO-8601形式の作成日時

[
 {
 "id": "string",
 "fileName": "string",
 "createdAt": "iso-8601"
 }
]

ステータスコード#

コード	説明
200	成功（0件の場合は空配列）

内部処理シーケンス#

sequenceDiagram
 autonumber
 actor User
 participant Hono as Hono Middleware
 participant Domain as Domain Service
 participant DB as Repository

 User->>+Hono: 一覧取得リクエスト
 Hono->>+Domain: 一覧取得リクエスト
 Domain->>+DB: findAll()
 DB-->>-Domain: [{id, fileName, createdAt}]
 Domain-->>-Hono: Success
 Hono-->>-User: 200 OK

懸案事項#

ユーザーごとの絞り込み未実装#

現状: 全ユーザーの画像を返却している
影響: 他ユーザーの画像が見えてしまう、プライバシー問題
対応方針: 認証ミドルウェアから取得したユーザーIDで絞り込み

パフォーマンス問題#

現状: 全件取得でページネーションなし
影響: 画像数増加時のレスポンス悪化、メモリ消費
対応方針: ページネーションとキャッシュ導入

TBD#

並び順とソート機能#

作成日順のデフォルトソート
ファイル名順、サイズ順のソートオプション
昇順・降順の指定

検索機能拡張#

ファイル名の部分一致検索
メタデータによる検索（将来的な機能拡張）
タグによる絞り込み

画像閲覧用URL取得

Mon, 01 Jan 0001 00:00:00 +0000

画像閲覧用URL取得#

ID#

api004-upload

エンドポイント#

メソッド	パス
GET	`/images/:id`

概要#

指定した画像IDに対応する閲覧用Presigned URLを取得する。

リクエスト#

パスパラメータ#

物理名	論理名	型	必須	説明
id	画像ID	string (UUID)	✓	閲覧したい画像のID

レスポンス#

200 OK#

物理名	論理名	型	必須	説明
url	閲覧用URL	string	✓	画像の閲覧用Presigned URL
expiresAt	有効期限	string	✓	URLの有効期限（ISO-8601形式）

{
 "url": "string",
 "expiresAt": "iso-8601"
}

ステータスコード#

コード	説明
200	成功
404	指定IDの画像が存在しない

内部処理シーケンス#

sequenceDiagram
 autonumber
 actor User
 participant Hono as Hono Middleware
 participant Domain as Domain Service
 participant DB as Repository
 participant S3 as S3 Client

 User->>+Hono: 閲覧URLリクエスト (id)
 Hono->>+Domain: 閲覧URLリクエスト (id)
 Domain->>+DB: findById(id)
 DB-->>-Domain: image (s3Key)
 Domain->>+S3: getSignedUrl (GetObject, s3Key, expires=3600)
 S3-->>-Domain: url
 Domain-->>-Hono: Success (url, expiresAt)
 Hono-->>-User: 200 OK

懸案事項#

アクセス権限の未実装#

現状: 画像IDさえ知っていれば誰でも閲覧可能
影響: 他ユーザーのプライベート画像にアクセス可能になる
対応方針: 画像所有者のみアクセス許可の認可チェック

画像API on 設計書

署名付きURL 発行

署名付きURL 発行#

ID#

エンドポイント#

概要#

リクエスト#

ボディ#

バリデーション#

Presigned URL 有効期限#

アップロード完了・メタデータ登録

アップロード完了・メタデータ登録#

ID#

エンドポイント#

概要#

リクエスト#

ボディ#

バリデーション#

マジックナンバー検証#

レスポンス#

201 Created#

ステータスコード#

内部処理シーケンス#

懸案事項#

S3とDB間の分散トランザクション#

画像一覧取得

画像一覧取得#

ID#

エンドポイント#

概要#

レスポンス#

200 OK#

ステータスコード#

内部処理シーケンス#

懸案事項#

ユーザーごとの絞り込み未実装#

パフォーマンス問題#

TBD#

並び順とソート機能#

検索機能拡張#

画像閲覧用URL取得

画像閲覧用URL取得#

ID#

エンドポイント#

概要#

リクエスト#

パスパラメータ#

レスポンス#

200 OK#

ステータスコード#

内部処理シーケンス#

懸案事項#

アクセス権限の未実装#

TBD#

アクセス制御の細粒度化#

キャッシュ戦略#