ColdBoxアプリケーション

ColdBoxアプリケーション

bxSites coldbox は ColdBox アプリケー ションを、ディスク上の規約からドキュメント化します。ルート、イベント ハンドラー、モデルと WireBox マッピング、モジュール、インターセプター、 スケジュールタスクが対象です。

アプリケーションを起動することはありません。コンパイルも不要、データソース への到達も不要、環境変数の設定も不要なので、CI ランナーでもローカルと同じ ように動きます。この方式で見えないものは、下の限界に明記して あります。

クイックスタート

bx-sites プロジェクトを兼ねている ColdBox アプリのルートで実行します。

bxSites coldbox
bxSites build

ページは docs/api/coldbox/ 以下に生成されます。アプリが別の場所にある 場合は次のように指定します。

bxSites coldbox --appRoot=app

設定

すべて省略可能です。完全なスキーマは coldbox を参照してください。

coldbox:
  appRoot: "."
  pagePathPrefix: api/coldbox
  tags: [ api, coldbox ]
  include: [ routes, handlers, models, modules, interceptors, scheduler ]

{
	"coldbox": {
		"appRoot": ".",
		"pagePathPrefix": "api/coldbox",
		"tags": [ "api", "coldbox" ],
		"include": [ "routes", "handlers", "models", "modules", "interceptors", "scheduler" ]
	}
}

[coldbox]
appRoot = "."
pagePathPrefix = "api/coldbox"
tags = [ "api", "coldbox" ]
include = [ "routes", "handlers", "models", "modules", "interceptors", "scheduler" ]

include は生成するページ群を決めます。トークンを外すと、そのページ群は まったく生成されません。各キーにはフラグがあります。

bxSites coldbox --appRoot=app --include=routes,handlers \
	--pagePathPrefix=reference --tags=reference,api

生成されるもの

docs/api/coldbox/
├── index.md               # アプリの概要と件数
├── routes.md              # すべてのルート（宣言順）
├── handlers/
│   ├── index.md
│   ├── Main.md
│   └── api/Orders.md      # モジュールのハンドラーはモジュール配下
├── models/
│   ├── index.md           # モデルとバインダーのマッピング
│   └── UserService.md
├── modules/
│   ├── index.md
│   └── api.md
├── interceptors.md
└── scheduled-tasks.md

ルート

アプリのルーターと各モジュールのルーターが宣言するすべてのルートを、宣言 された順に並べます。ColdBox は最初に一致したパターンを採用するため順序に 意味があり、ページもその順序を保ちます。resources()/apiResources() は ColdBox が生成する個々のルートに展開され、モジュールのルートは実際に マウントされているエントリーポイントを反映します。

ハンドラー

ハンドラーごとに1ページ。そこへ到達するルートと、それぞれが呼び出す アクションを示し、続けて呼び出し可能なアクションをドキュメントコメントと 引数つきで並べます。ColdBox 自身のライフサイクルフック（preHandler、 aroundHandler、onError など）は URL から到達できるアクションとしてでは なく、独立したセクションにまとめます。init と private メソッドは含めま せん。

モデル

モデルごとに1ページ。スコープ、WireBox が注入するもの、モデル自身の プロパティ、public メソッドを示します。注入された依存関係は通常の プロパティとは分けて表示します。property name="x" inject="y" は配線で あってデータではないからです。インデックスにはバインダーが宣言した マッピングも並びます。

モジュール、インターセプター、スケジュールタスク

モジュールページには、その ModuleConfig が宣言する内容（作者、バージョン、 エントリーポイント、依存関係）と、そのモジュールがアプリに加えるものが 並び、それぞれ説明ページへリンクします。インターセプターのページは ColdBox が見つける2つの経路の両方、つまり config/ColdBox が登録するものと interceptors/ が宣言するものを扱い、各クラスの public メソッドを インターセプションポイントとして列挙します。タスクのページは config/Scheduler と各モジュールのスケジューラーを読み取ります。

DocBox でより詳細なページに

ルート、モジュール、インターセプター、アプリの全体像は規約だけから得られ ます。クラス単位の詳細（ハンドラーのアクション、モデルのメソッド、その 引数やコメント）は DocBox から取得するため、bx-docbox を 入れるとこれらのページは大幅に充実します。

install-bx-module bx-docbox

なくても verb は動作し、ハンドラー・モデル・ルート・モジュールはすべて 列挙されます。ページには不足している情報と、その入手方法が明記されます。

限界

静的な読み取りには明確な限界があり、それは隠さず示すべきものです。 アプリケーションが実行時に決めることは、ディスク上には存在しません。

• パターンやターゲットを変数から組み立てるルート、ループ内で登録される ルート。
• 名前が計算される WireBox マッピングやスケジュールタスク。
• modules_app/ にコミットされず、起動時にインストールされるモジュール。
• mapDirectory() が実際に登録する内容。これは起動時にディスク上に何が あるかで決まります。

これらはいずれも推測せずスキップします。生成されたページは、誤ったことを 書くより控えめに書きます。

Gradle や Maven からは利用できません

これは意図的です。ColdBox アプリケーションは CommandBox でビルド・実行する ものであり、Java のビルドツールで扱うものではないため、 bxSitesColdBoxDoc タスクも bxsites:coldbox ゴールも存在しません。 Gradle と Maven のプラグインが提供 するのは DocBox ジェネレーターで、こちらはビルド対象の JVM プロジェクトに実際に含まれる BoxLang/CFML クラスを対象とします。