Nijo Application Builder 【開発中 under development】

概念データモデルから一般的なエンタープライズ系業務アプリケーションのひな形を自動生成するツール。

目次 Table of contents

Nijo Application Builder 【開発中 under development】

お試し Getting Started

以下のツールが使えるようにしておいてください。

dotnet (バージョン 8.0.102 以上) : Microsoftの公式サイト等からインストールしてください。
npm (バージョン 9.6.3 以上) : Node.jsの公式サイト等からインストールしてください。

ターミナルからコマンドを実行し、使用可能ならOKです。以下の例ではそれぞれ使用可能ならバージョンが表示されます

dotnet --version
npm --version

このリポジトリのReleasesページから実行可能なバイナリファイルをダウンロードして解凍してください。以下の例では C:\your-installed-directory に解凍したものとして説明を進めます。

ターミナルやコマンドプロンプトから以下を実行してください。アプリケーションが作成されます。

C:\your-installed-directory\nijo create MyProject

ターミナルやコマンドプロンプトから以下を実行してください。

cd MyProject
C:\your-installed-directory\nijo debug

自動生成されたアプリケーションが実行されます。
- ブラウザからアプリケーションを閲覧してください。規定では https://localhost:5713 でアクセスできます。
- 保存されたデータはMyProjectディレクトリ直下の拡張子 .sqlite3 ファイルに保存されています。データの閲覧方法はSQLite公式サイト等を参照してください。
nijo.xml や、MyProjectディレクトリ内のソースコードを編集して、あなたのアプリケーションをカスタマイズしてください。

以上

概要図 Overview, Usage

このツールでアプリケーションを生成する手順と、どういったパーツが生成されるかを示します。

概念データモデルを定義する
コード自動生成を実行する
自動生成で賄えない機能を自前で実装する

概要図 overview

1. 概念データモデルを定義する

前述の Getting Started を参照し、 nijo コマンドラインツールを使用できるようにしてください。

作成されたディレクトリの中に nijo.xml という名前のファイルがあります。これをテキストエディタで編集し、あなたのアプリケーションで取り扱うデータの構造を定義してください。

具体的・詳細な指定方法は自動テストのXML を参照してください。 以下では基本的な考え方のみを説明します。

基本的な考え方

登録・更新・削除されるデータのまとまりごとにデータ構造を定義してください。なおこのプロジェクトでは、このデータのまとまりを「集約（Aggregate）」と呼称しています。

そのデータ構造がもつことのできる子孫（子要素、入れ子構造）の種類には以下の3種類があります。

単一の子要素（Child）

親1件に対する1件の入れ子データ。具体的な設定方法はユニットテストのXML 003_Childのみ.xml を参照してください。

例：「取引先」データの構造

取引先ID
取引先名
宛先 ← これがChild
- 郵便番号
- 住所
- 電話番号

複数の子要素（Children）

親1件に対する複数件の入れ子データ。具体的な設定方法はユニットテストのXML 002_Childrenのみ.xml を参照してください。

例：「発注」データの構造

発注番号
発注者名
発注日
明細 ← これがChildren
- 連番
- 商品名
- 個数
- 希望納品日

多態子要素（Variation）

親1件に対する1件の入れ子データ、ただし異なるデータ構造をもつ複数のバリエーションから1つを選択するもの。具体的な設定方法はユニットテストのXML 004_Variationのみ.xml を参照してください。

例：「旅費申請」データの構造

申請番号
申請者名
申請日
内訳 ← これがVariation（宿泊費または交通費のうちどちらかが択一で選択される）
- 宿泊費
- 日程
- 合計金額
- 宿泊先名
- 交通費
- 移動日
- 区間
- 片道金額
- 片道か往復か

また、登録・更新・削除されるタイミングが異なる別のデータへの参照を定義することができます。

他集約への参照（Ref）

登録・更新・削除されるタイミングが異なる別のデータへの参照。具体的な設定方法はユニットテストのXML 001_Refのみ.xml を参照してください。

例：

受注
- 受注番号
- 明細
- 受注明細番号
- 商品名
- 個数
出荷指示
- 出荷予定日
- 出荷担当者名
- 明細
- 受注明細 ← これがRef。受注番号と受注明細番号の複合キーをもつ
- 備考

2. コード自動生成を実行する

上記で作成したデータモデルでコード自動生成を実行し、動作確認を開始するため、ターミナルから以下のコマンドを実行してください。

cd <nijo.xmlがあるディレクトリ>
C:\your-installed-directory\nijo.exe debug

注意点

デバッグの度にテストデータが消えてしまうのを防ぐため、データベース定義の自動生成は自動では実行されないようになっています。生成されたWebアプリケーションのトップページにデータベース定義を再作成するボタンがあるので、そのボタンを押してデータベースを作成してください。
画面を開いた瞬間にエラーが出る場合
- HTTPSの証明書の問題で、Reactのプロセスが .NET Core のプロセスにアクセスできていない可能性があります。コマンドラインで dotnet dev-certs https を実行してみてください。
- Windowsでこの証明書が「信頼されたルート証明書」にならないケースがあるので注意（条件不明）。その場合はWindowsメニューの「ユーザー証明書の管理」でdotnetの証明書を信頼されたルート証明書にしてください。
動作確認を行わず、コードの自動生成のみを実行する場合は以下のコマンド。

cd <nijo.xmlがあるディレクトリ>
C:\your-installed-directory\nijo.exe update

3. 自動生成で賄えない機能を自前で実装する

自動生成されるソースを編集する
- 執筆中
自動生成された後のソースを編集する
- ASP.NET Core Web API
- __AutoGenerated フォルダの中身は編集しないこと！
  - このディレクトリの中はコード自動生成のたびに洗い替えられるため
- Program.cs
  - 執筆中
- OverridedApplicationService.cs
  - 執筆中
- DbContext
  - 執筆中
- React
- src/__autoGenerated フォルダの中身は編集しないこと！
  - このディレクトリの中はコード自動生成のたびに洗い替えられるため
- App.tsx
  - 執筆中

4. リリース

データベース定義についての仕組みは特に用意していません。 Entity Framework Core の仕組みを使っているので dotnet-ef によるマイグレーションが最適と思われます。
- 【備忘】標準的な dotnet-ef の使い方（2024-06-23記載。dotnet-efのバージョンは8.0.6）
- リリースするタイミングで以下を実行
  - dotnet ef migrations add 0000 （0000はバージョンを表す任意の文字列）でマイグレーションを作成
  - dotnet ef migrations script 0000 でSQL文を生成（0000は1個前のバージョンの名前）。SQLはコンソールに吐かれるので適宜ファイルに出力すること
執筆中

nijo.xmlの各集約に使用できる属性

こちらも併せて参照してください。

ルート要素に使用できる属性

is 属性に指定できるもの
- write-model-2
- このルート要素がDB保存されるべきデータであることを表します。
- Entity Framework Core のエンティティ定義や、作成・更新・削除のWeb API エンドポイントなどが生成されます。
- generate-default-read-model を併せて指定することで、write-model-2から生成されるモジュールだけでなく、まったく同じデータ構造のread-model-2のモジュールも生成されます。
- read-model-2
- このルート要素が、人間が閲覧するデータであることを表します。
- React.jsでの一覧検索画面（MultiView）、詳細画面（SingleView）、一括編集画面（MultiViewEditable）などが生成されます。
- read-model-2 のis属性では以下の属性を任意で指定することができます。
  - form-label-width:(小数)
  - 検索条件欄や詳細画面のフォームのラベルの横幅。単位はCSSのrem。
  - form-depth:(整数)
  - 検索条件欄や詳細画面のフォームのラベルの左端列のインデントに影響します。
  - readonly
  - 新規作成画面、詳細画面（編集モード）、一括編集画面へのリンクがなくなります。
- enum
- このルート要素が列挙体であることを表します。
- command
- このルート要素が、人間や外部システムが起動する処理のパラメータであることを表します。
- 起動用のWebAPIエンドポイントや、React.jsの起動用ダイアログのコンポーネントなどが生成されます。
- commandの直下に is="step:(整数)" 属性の要素を定義すると、ダイアログのコンポーネントなどのUIが、1ステップごとに少しずつ項目を入力していくウィザード画面になります。stepを定義する場合は直下の要素を全てstepにする必要があります。
DisplayName
- 画面表示名称を指定できます。その属性名に、スペースやハイフンやスラッシュなど、プログラムで利用できない文字列が含まれる場合に有効です。（例:「注文履歴/最新」など）
DbName
- データベースのテーブル名やカラム名を指定します。
Latin
- URLなど日本語名が使えないものの名称をカスタマイズする場合はこれを指定します。
- 「Customer Destination Information」などのように半角スペース区切りで記載してください。

子孫要素に使用できる属性

is 属性に指定できるもの
- child
- 前掲「単一の子要素（Child）」の項を参照。
- children
- 前掲「複数の子要素（Children）」の項を参照。
- variation
- 前掲「多態子要素（Variation）」の項を参照。
- variationの直下に指定できるのは is="variation-item:(整数)" のみです。
- ref-to:参照先の集約
- 前掲「他集約への参照（Ref）」の項を参照。
- 参照先がルート要素ではなく子孫要素の場合は ref-to:親要素/子要素/孫要素 のようにスラッシュで区切ってください。
- 値型（word, int, date など）
- 012_スカラメンバー網羅.xml を参照
- is="enum" で指定されたルート要素を列挙体として使用することもできます
Refまたは値型の is 属性には、以下を任意で指定することができます。
- key
- その属性がその集約のキーであることを表します。
- ルート要素またはChildrenの直下の項目のうち、指定可能。
- name
- その属性がその集約の表示名称であることを表します。詳細画面のタイトルや、コンボボックスの表示名称に使われます。
- ルート要素またはChildrenの直下の項目のうち、Refまたは値型に対して指定可能。
- 未指定の場合はkeyが表示名称に使われます。
- wide
- 詳細画面における当該項目の横幅が画面いっぱいに広がります。
- hidden
- 画面上で非表示になります。
- single-view-ui:(任意の物理名), search-condition-ui:(任意の物理名)
- 詳細画面や検索条件欄における当該項目のUIを任意のコンポーネントに変更できます。コンポーネントは個別実装される必要があります。
- width:(z + 整数) または width:(h + 整数)
- 詳細画面における当該項目の横幅を変更できます。全角10文字の場合は "z10"、半角6文字の場合は "h6" など、zかhのあとに整数を続けてください。
- combo または radio
- 列挙体のメンバーまたはバリエーションにのみ使用可能。詳細画面の入力フォームがコンボボックスまたはラジオボタンに固定されます。指定しない場合は動的に決まります（選択肢の数が多ければコンボボックス、少なければラジオボタン）。
- バリエーションに指定する場合、is="variation" の要素ではなく is="variation-item:1 radio" のように最初の要素に指定する必要あり。将来的に修正予定。
DisplayName, DbName, Latin
- ルート要素のそれと同様です。

nijo.xmlのスキーマ定義をTSV出力する

Excelやスプレッドシートに貼り付けてスキーマ定義全体を俯瞰してください。

nijo.exe dump

nijo.xmlのスキーマ定義をmermaid.js記法で出力する

nijo.xmlの各集約の定義をグラフ形式で概観するのに使ってください。

nijo.exe dump --mermaid

Contributing

コーディング規約
- Visual Studio Code
- .editorconfig が有効化される拡張機能をインストールすること
- 一部の.editorconfig設定（特にC#側の設定）は拡張機能のインストールのみでは有効化されないため、以下を行うこと
  - settings.jsonにて "dotnet.server.useOmnisharp": true を設定すること
  - C#(powered by omnisharp) 拡張機能をインストールすること

デモ Demo

このプロジェクトには、ユニットテストに用いているデータパターンがいくつか存在します（どのようなパターンがあるかはこちらを参照してください）。それらのパターンを実際に動作させ、どのようなUIや処理やDBが生成されるかを細かく確認するための手順を以下に示します。

このリポジトリをクローンしてください。
ユニットテストプロジェクト Nijo.IntegrationTest で様々なパターンのデータ構造定義をテストしています。「コンパイルエラーチェック」という名前のテストがあるので、閲覧したいデータ構造定義のテストを実行し、生成されたプロジェクトで実物の動作を確認してください。
- ユニットテストの実行方法はNUnitの通常の実行方法に従ってください。開発者は Visual Studio のテストエクスプローラーから実行しています。
上記テストの実行に成功した場合、 /自動テストで作成されたプロジェクト ディレクトリにプロジェクトが生成されます。このプロジェクトのルートディレクトリ（ nijo.xml があるディレクトリ）でターミナルやコマンドプロンプトを開き、 nijo debug コマンドを実行してください。
- Webサイトはlocalhostで実行されます。
- クライアントサイド（React SPA）のポート等は /自動テストで作成されたプロジェクト/react/vite.config.ts で指定されています。詳細な設定方法はViteの公式を参照してください。
- サーバーサイド（ASP.NET Core Web API）のポート等は /自動テストで作成されたプロジェクト/webapi/Properties/launchSettings.json で指定されています。
DB定義やデータの確認
- このWebサイトで登録されたデータは、プロジェクトのルートディレクトリにある、拡張子が sqlite3 のファイルに格納されています。このファイルの開き方はSQLiteの公式を参照してください。
自動生成されたソースコードの内容の確認
- サーバーサイドの自動生成ソースは /自動テストで作成されたプロジェクト/webapi/__AutoGenerated/ に展開されます。
- クライアントサイドの自動生成ソースは /自動テストで作成されたプロジェクト/react/src/__autoGenerated/ に展開されます。

このソフトウェアを作成した動機 Motivation

画面からDBまでを一気通貫でカバーしてくれるちょうどよいライブラリ・フレームワークが欲しかった。
CRUD機能のうちCUDは自動生成する効果が大きいと感じていた。
- データの形が違うだけで気を付けなければいけないポイントはだいたいいつも同じ（キー重複の考慮、同時編集や排他制御、更新データ中に配列がある場合の実装の大変さ、二重登録の考慮、トランザクションの切り方、など）
- その割には品質が低い場合のシステム全体に及ぼす実害が参照系処理に比べてとても大きい
- システムの主要なデータではない補助的なデータ（いわゆるトランザクションデータに対するマスタデータのこと）について、機能要件が緩くなりがち（登録更新さえできればUIは割とどうでもいい）な割に上記の通り実装が大変なので、ここが自動生成されるととても助かる
データモデル駆動の要件定義のため。
- ウォーターフォール開発の要件定義フェーズにおいて、チーム内でデータモデルの議論を軸にして検討を進めたいことがよくある。そこではメンバー間で実際に動くデータを見つつ認識共有しながら進まないと議論が空中戦になるのだが、そのためにはデータモデルのたたき台を考えてから実際に動くデータができるまでを数分程度で実現できるツールが必要だった。
上記のような要件を満たしつつ、通常のスクラッチ開発と同レベルの柔軟性をもったツールが欲しかった
- ネストされた子要素、伝票の明細など子要素の配列、多態性をもった子要素、他のデータへの参照、といった複雑なデータ構造を定義できてほしい
- 複雑なデータについてパフォーマンスを落とさず高速なクエリを発行するためにはCQRSや生SQLの実装ができるようになっていてほしい
- 日次業務のオペレーションに耐えうる画面、現行の業務フローに合致した画面、など厳しい要件を満たすためには画面のソースをゼロから組み上げられるようになっていてほしい
オンプレにしようと思えばオンプレにもできるアーキテクチャ
- いわゆるエンタープライズ系システム・基幹寄りのシステムは、寿命が長いのでフルマネージドであっておきたい
- クラウド型のSaaSは提供事業者の意思次第でいつでも使えなくなりうる

License

This software is released under the MIT License. see LICENSE.txt.

halllky / NijoApplicationBuilder

readme