WAGBY11 MANUAL / 31
ファイル型の詳細
ファイル型のDB構造、実ファイルの保存先と命名方式、再生成で保持される外部設定、更新・削除時の扱いを説明します。
最終更新日:
1. このページで伝える機能
ファイル型は、業務データに添付資料や画像を持たせる項目です。DBには元ファイル名などの参照情報を保存し、ファイル本体はREST APIサーバーから読み書きできるファイルシステムへ保存します。ファイル項目の基本的な使い方は、ファイルを扱うも参照してください。
このページでは、DBと実ファイルの対応、保存先の変更方法、コード再生成後も保持する設定の置き場所を説明します。
2. Wagby11で実現できること
2.1 DBで管理する情報
1つのtype: file項目は、JavaではFileReferenceとして扱われ、DBでは4列に展開されます。ファイル本体をDBのBLOBへ格納する方式ではありません。DB物理名がATTACHMENTの場合の例です。
| DB列 | 内容 | 型 |
|---|---|---|
ATTACHMENT | 保存ルートからの相対パス(relativePath) | VARCHAR(1024) |
ATTACHMENT_ORIGINAL_NAME | アップロード時の元ファイル名(originalFilename) | VARCHAR(512) |
ATTACHMENT_CONTENT_TYPE | Content-Type(contentType) | VARCHAR(255) |
ATTACHMENT_SIZE | バイト単位のサイズ(size) | BIGINT |
元ファイル名と保存ファイル名は別に扱います。画面表示やダウンロード名には元ファイル名を使い、DBには保存ルートの絶対パスやダウンロードURLを保持しません。
2.2 実ファイルの保存先
保存ルートを指定する設定はapp.storage.root-directoryです。これはSpring Bootの外部設定プロパティで、AppSchemaの構文ではありません。省略時は./data/filesで、REST APIアプリケーションの実行時カレントディレクトリを基準に解決します。
保存ルートの設定:/srv/wagby/files
DBの相対パス:dailyreport/quotationfile1/2026/11/abc123.pdf
実ファイル:/srv/wagby/files/dailyreport/quotationfile1/2026/11/abc123.pdf
必要なディレクトリは保存時に自動作成します。実行ユーザーが保存先を読み書きできるようにしてください。項目別に設定するfile_storageは、命名方式や容量・形式の制約を指定するもので、保存ルートの指定ではありません。
2.3 再生成で保持される外部設定
保存先の変更は、製品ルートのconfig/application.ymlへ記述します。この利用者設定ファイルはコード再生成の対象外です。restapi/src/main/resources/application.ymlを直接編集する必要はありません。
製品ルート/
├── config/
│ └── application.yml ← 利用者設定
└── restapi/
└── src/main/resources/application.yml
config/application.ymlに次を記述します。既に設定がある場合は、既存の内容を残して追加します。同じappキーがある場合は、その配下にまとめてください。
app:
storage:
root-directory: /srv/wagby/files
REST API側には、次の外部設定読み込みがあらかじめ用意されています。
spring:
config:
import: optional:file:${WAGBY_CONFIG_DIR:../config}/application.yml
標準起動スクリプトはrestapiをカレントディレクトリにするため、既定で隣のconfig/application.ymlを読み込みます。設定フォルダを別の場所に置く場合は、環境変数WAGBY_CONFIG_DIRにフォルダの絶対パスを指定します。環境変数の一覧は設定する環境変数を参照してください。
変更後はREST APIを再起動します。外部設定の変更だけなら、コード再生成や再ビルドは不要です。同じ項目を起動時のコマンドライン引数で指定している場合は、そちらが優先されます。保存ルートには絶対パスを指定すると、起動場所による違いを避けられます。
相対パスの保存ルートは、外部設定ファイルの置き場所ではなくREST APIの実行時カレントディレクトリが基準です。また、項目単位のマージはリストを要素ごとに追加する意味ではありません。このページの例は単一の保存先プロパティを上書きします。
2.4 保存ファイル名の方式
項目のfile_storage.filename_strategyで保存ファイル名の方式を選べます。省略時はgeneratedです。通常の生成コードでは、分類にモデルと項目を表すdailyreport/quotationfile1などを使い、保存時の日付による年月の下へ配置します。
| 方式 | 保存ルート配下の構造 | 特徴 |
|---|---|---|
generated | {分類}/{年}/{月}/{UUID}{拡張子} | 元ファイル名の拡張子を引き継ぎ、本体の名前を生成します。 |
sanitized_original | {分類}/{年}/{月}/{UUID}/{安全化した元ファイル名} | 禁止文字などを置換した名前を使い、一意のディレクトリで同名衝突を避けます。 |
安全化では、パス部分の除去、UnicodeのNFC正規化、禁止文字・制御文字の置換、末尾の空白・ピリオドの除去、Windows予約名の回避などを行います。いずれの方式も、表示用の元ファイル名は別途DBに保持します。
2.5 登録・取得・更新・削除
登録・更新ではmultipart/form-dataで業務JSONとファイルを送信します。元ファイル名はmultipartのfilenameから取得します。通常の一覧・詳細レスポンスは元ファイル名、Content-Type、サイズを返し、内部の相対パスは公開しません。
ファイルはGET /dailyreports/{id}/files/quotationfile1のような項目別APIから取得します。元ファイル名をダウンロード名に使い、通常のEntity参照と同じ認証・モデル権限・行権限を適用します。Entity、ファイル参照、実ファイルが見つからない場合は404として扱います。
| 操作 | 扱い |
|---|---|
| 登録 | 新ファイルを保存し、参照情報をDBに登録します。 |
| 更新でファイル未送信、削除指定なし | 既存ファイルを維持します。 |
| 更新で新ファイル送信 | 新ファイルへ置換し、旧ファイルはDBコミット後に削除します。 |
removeXxx: true | ファイル参照をnullにし、旧ファイルはDBコミット後に削除します。 |
| Entityの物理削除 | 参照していた添付ファイルもDBコミット後に削除します。 |
| Entityの論理削除 | DBの参照情報と添付ファイルを保持します。 |
置換ファイルと削除フラグの同時指定はエラーです。not_null: trueの必須ファイルも削除できません。更新で既存ファイルを維持する場合は再送不要です。
DBとファイルシステムは同じトランザクションへ参加しないため、補償処理で整合性を保ちます。DBがロールバックした場合は新ファイルを削除し、旧ファイルは残します。コミット後の削除がI/Oエラーになった場合はログへ記録されるため、孤立ファイルの確認・保守も必要です。
2.6 バックアップと配備環境
保存先の変更だけでは既存ファイルを移動しません。停止などで更新を止め、相対ディレクトリ構造を保って新しい保存ルートへファイルを移してから設定を変更します。DBの相対パスを書き換える必要はありません。
DBと実ファイルの両方を対応する時点でバックアップ・復元します。DBだけを復元しても添付ファイル本体は戻りません。保存先の容量とinodeも監視します。
AWS標準配備では、H2テスト構成は/opt/wagby/restapi/data/filesの一時領域、本番構成は既定で/mnt/wagby/filesのEFS領域へ保存します。本番ではEFSの/wagbyを/mnt/wagbyへマウントするため、EFS側の保存先は/wagby/files配下に対応します。
AWS配備では保存先を起動時に管理しており、利用者設定のapp.storage.root-directoryによる任意変更は制限されます。通常起動の外部設定例を、そのままAWS配備へ適用しないでください。H2テスト構成の更新では添付ファイルも初期化されるため、永続的な保管には本番構成を使います。
3. AIへの指示例
最小限の指示例
受付情報に添付資料のファイル項目を追加してください。実ファイルは /srv/wagby/files に保存し、保存先の設定は再生成後も保持してください。AIは項目の英語識別名、画面上の配置、保存ファイル名の方式など、未指定の仕様を類推して補います。許可形式や容量、必須かどうかに条件がある場合は追加で伝えてください。最小限の指示だけで、次の詳細例と同じ仕様になるとは限りません。
より詳細な指示例
既存の受付情報モデルに、任意入力の「添付資料」(attachment)をファイル型で追加してください。
保存名はgenerated、最大10 MiB、許可するContent-Typeはapplication/pdfとします。
製品ルートのconfig/application.ymlへapp.storage.root-directory: /srv/wagby/filesを設定してください。
既存の外部設定は保持し、生成ソース内のapplication.ymlは直接編集しないでください。
登録・表示・取得、ほかの項目だけを更新した場合のファイル維持、置換・削除を確認してください。
DBには保存ルートからの相対パスと元ファイル名などが保存されること、コード再生成後も外部設定が保持されることを確認してください。4. 編集されるAppSchemaの例
ファイル項目の定義例です。
entity:
attributes:
- name: 添付資料
name_en: attachment
type: file
file_storage:
filename_strategy: generated
max_size_bytes: 10485760
allowed_content_types:
- application/pdf
file_storage自体の省略時も保存名はgeneratedです。max_size_bytesとallowed_content_typesの省略時は項目単位では制限しませんが、Spring Bootやリバースプロキシのリクエスト容量制限は別に適用されます。Content-Typeはmultipartの申告値で検証し、ファイル内容の形式判定やウイルススキャンは別途追加します。
保存先を指定するapp.storage.root-directoryはこのAppSchemaへ追加せず、前述のconfig/application.ymlへ記述します。
5. 参考資料
- guide:エンティティ属性タイプ
designer/docs/appschema/markdown/guide/03-model/02-fields.md- reference:entity
designer/docs/appschema/markdown/reference/06-entity.md- AWS:Pipelineによるアプリ配置
aws-deployer/docs/deployment.md