From 9a7bee324cdff4e98c3fe45019e1d7f9283ad5a1 Mon Sep 17 00:00:00 2001 From: Akihito Koriyama Date: Fri, 19 Apr 2024 09:54:03 +0900 Subject: [PATCH] Reorganize technical documentation sections and update headings This commit rearranges the structure of the technical documentation, converting the main sections into second-level headings and the subsections into their lower-level headings. The aim is to enhance readability and understanding of the document's content by clarifying the information hierarchy. --- manuals/1.0/ja/15.tech.md | 94 ++++++++++++++++++++------------------- 1 file changed, 49 insertions(+), 45 deletions(-) diff --git a/manuals/1.0/ja/15.tech.md b/manuals/1.0/ja/15.tech.md index 10e53f3b..5342585f 100644 --- a/manuals/1.0/ja/15.tech.md +++ b/manuals/1.0/ja/15.tech.md @@ -7,17 +7,18 @@ permalink: /manuals/1.0/ja/tech.html # 技術 この章では、BEAR.Sundayの機能と技術的特徴を説明します。 +## アーキテクチャと設計原則 -## リソース指向アーキテクチャ (ROA) +### リソース指向アーキテクチャ (ROA) > "Resources interconnected, like the web of life that binds all creatures.” BEAR.Sunday のROAは、Web アプリケーション内でRESTful APIを実現するアーキテクチャです。これはBEAR.Sundayの設計原則の核となるものであり、ハイパーメディアフレームワークであると同時に"サービスしてのオブジェクト(Object as as service)"をとして扱います。Webと同様に、全てのデータや機能をリソースとみなし、GET、POST、PUT、DELETEなどの標準化されたインターフェースを通じて操作します。 -### URI +#### URI URI（Uniform Resource Identifier）はWebの成功の鍵となる要素であり、BEAR.SundayのROAの中核でもあります。アプリケーションが扱うすべてのリソースにURIを割り当てることで、リソースを識別し、アクセスしやすくなります。 URIは、リソースの識別子として機能するだけでなく、リソース間の関係を表現するためにも使用されます。これにより、リソースの操作、再利用、組み合わせが容易になります。 -### ユニフォームインターフェース +#### ユニフォームインターフェース リソースへのアクセスはHTTPのメソッド（GET, POST, PUT, DELETE）を用いて行われます。これらのメソッドはリソースに対して実行できる操作を規定しており、リソースの種類に関わらず共通のインターフェースを提供します。 @@ -26,7 +27,7 @@ URI（Uniform Resource Identifier）はWebの成功の鍵となる要素であ - PUT: リソースに対して冪等性のある操作を行う（作成または更新など） - DELETE: リソースを削除する -## ハイパーメディア +#### ハイパーメディア BEAR.Sunday のリソース指向アーキテクチャ (ROA) では、各リソースがハイパーリンクを通じてアフォーダンス（クライアントが利用可能な操作や機能）を提供します。これらのリンクは、クライアントが利用できる操作を表し、アプリケーション内をナビゲートする方法を指示します。これにより、クライアントとサーバー間の結合度が低くなり、アプリケーションの柔軟性と拡張性が高まります。 @@ -35,11 +36,11 @@ BEAR.Sunday のリソース指向アーキテクチャ (ROA) では、各リソ BEAR.Sunday のハイパーメディアアプローチは、Webの原則に沿った設計であり、アプリケーションの柔軟性と拡張性を高めます。 -### 値と表現の分離 +#### 値と表現の分離 BEAR.SundayのROAでは、リソースの値と表現が明確に分離されています。リソースの値はアプリケーションのドメインロジックによって管理され、表現はその値を様々な形式（JSON, XML, HTMLなど）で表現するためのものです。この分離によってドメインロジックとプレゼンテーションロジックが疎結合になり、アプリケーションの保守性と拡張性が向上します。 -### pageリソースとappリソース +#### pageリソースとappリソース BEAR.SundayのROAでは、リソースはpageリソースとappリソースの二つに分類されます。 @@ -50,7 +51,7 @@ pageリソースとappリソースを分離することで、ユーザーイン BEAR.SundayのROAを用いることで、Webの設計原則に沿ったスケーラブルで疎結合なアプリケーションを構築できます。値と表現の分離によってドメインロジックとプレゼンテーションロジックを独立に開発・テストできるため、アプリケーションの品質と開発効率が向上します。またpageリソースとappリソースを分離することで、ユーザーインターフェースとアプリケーションロジックを独立に開発・デプロイでき、アプリケーションの柔軟性と拡張性が向上します。またハイパーリンクはリソース間の関係性を明示し、クライアントとサーバー間の結合度を低く保ちリソースの自己記述性やAPIの発見性を高めます。 -### MVCとの相違点 +#### MVCとの相違点 BEAR.SundayのROAは、従来のMVCアーキテクチャとは異なるアプローチをとっています。MVCはモデル、ビュー、コントローラーの3つのコンポーネントでアプリケーションを構成しますが、実際はコントローラーがモデルやビューを自由にランタイムで操作し、あくまでコントローラーが文字通り全てをコントロールしています。 @@ -63,7 +64,7 @@ BEAR.SundayのROAは、従来のMVCアーキテクチャとは異なるアプロ - MVCのモデルと違って、コンソールを含む多様なクライアントから直接コールすることができます。 - HTMLサイトとAPIサイトを別々に構築する必要がなく、同じリソースを使ってHTMLサイトとAPIサイトを同時に構築できます。 -## 依存性の注入 (DI) +### 依存性の注入 (DI) > "Objects are injected from the interface, just as sun ray is injected when a window is opened." @@ -75,7 +76,7 @@ DIを使用すると、アプリケーションの構造が改善され、コン BEAR.SundayのDIは[Ray.Di](https://github.com/ray-di/Ray.Di)という独立したパッケージを使用しており、Google社製のDIフレームワークであるGuiceの設計思想を取り入れ、ほぼすべての機能をカバーしています。 -### コンテキストによる束縛 +#### コンテキストによる束縛 例えば、ベースのアプリケーションにHTMLとPRODという2つのコンテキストを持つアプリケーションを考えます。HTMLコンテキストでは、リソース表現についてJSONビューが束縛されていたものがHTMLビューの束縛に変わります。PRODでArrayキャッシュに束縛されていたはキャッシュインターフェイスがRedisキャッシュが束縛されます。このように複数のコンテキストの束縛を重ねることでアプリケーションコードに変更はなくとも異なる振る舞いをすることができます。 @@ -93,7 +94,7 @@ DEBUGモードかどうかIF文で見て、実行中に振る舞いを変える Ray.Di logo -## アスペクト指向プログラミング (AOP) +### アスペクト指向プログラミング (AOP) > "Aspects wrap your objects, like a gift wrap enhances a present." @@ -106,7 +107,9 @@ BEAR.SundayのAOPはRay.Aopという独立したパッケージを使用して AOPは誤解の多い技術の一つです。その存在意義は強力な力のために制約を無視して秩序を壊すものではなく、探索的な機能の割り当てや横断的処理の分離などオブジェクト指向が不得意とする分野を補完し、アプリケーション横断的な制約を作る、つまりアプリケーションフレームワークの制約として設計が可能なパラダイムの1つです。 -## モダンCDNとの統合によるROAベースのイベントドリブンコンテンツ戦略 +## パフォーマンスとスケーラビリティ + +### モダンCDNとの統合によるROAベースのイベントドリブンコンテンツ戦略 > "No volatility, just what users truly desire." @@ -114,24 +117,30 @@ BEAR.Sundayは、リソース指向アーキテクチャ（ROA）を中核とし 揮発性を排除したこのアプローチは、SPOF（Single Point of Failure）を回避し、高い可用性と耐障害性を実現するだけでなく、ユーザー体験とコスト効率を最大化させ、ダイナミックコンテンツでもスタティックコンテンツと同じWeb本来の分散キャッシングを実現します。つまり、Webが1990年代から持っていたスケーラブルでネットワークコストも削減する分散キャッシュという原則を、現代的な技術で再実現しているのです。 -### セマンティックメソッドによるキャッシュ無効化 +#### セマンティックメソッドによるキャッシュ無効化 BEAR.SundayのROAでは、各リソース操作にセマンティック（意味的な役割）が与えられています。例えば、GET メソッドはリソースを取得し、PUT メソッドはリソースを更新します。これらのメソッドがイベントドリブン方式で連携し、関連するキャッシュを効率的に無効化します。たとえば、特定のリソースが更新された際には、その変更が依存する他のリソースに自動的に伝播し、関連するキャッシュが無効化されます。これにより、データの一貫性と新鮮さが保たれ、ユーザーに最新の情報が提供されます。 -### 埋め込みリンクによる依存関係の可視化 +#### 埋め込みリンクによる依存関係の可視化 ROAの設計では、リソースは他のリソースへのリンクを含むことができ、これによりリソース間の依存関係がクライアントに透明に示されます。このリンク情報を活用することで、キャッシュの無効化が必要な場合にどのリソースが影響を受けるかを瞬時に判断でき、効率的なキャッシュ管理が可能になります。 -### 引数の宣言によるキャッシュキー生成 +#### 引数の宣言によるキャッシュキー生成 BEAR.Sundayでは、リソースメソッドの引数が明確に宣言されています。これにより、リソースの状態やリクエストパラメータに基づいて独自のキャッシュキーを生成することができます。キャッシュキーの生成は、リソースの状態が変更されたときに特定のキャッシュを正確に特定し、無効化するための重要なメカニズムです。これにより、不必要なキャッシュの削除を避けつつ、必要な部分だけを迅速に更新することができます。 -### ETagによる同一性確認と迅速な応答 +#### ETagによる同一性確認と迅速な応答 システムがブートする前にETagを設定することで、コンテンツの同一性を迅速に確認し、変更がなければ304 Not Modified応答を返します。これはネットワークの負荷を減少させ、ユーザーエクスペリエンスを向上させるための効果的な手法です。 -### ドーナッツキャッシュとESIによる部分的な更新 +#### ドーナッツキャッシュとESIによる部分的な更新 BEAR.Sundayでは、ドーナッツキャッシュ戦略を採用しており、Edge Side Includes (ESI)を使用してCDNエッジで部分的なコンテンツ更新を可能にしています。この技術により、ページ全体を再キャッシュすることなく、必要な部分だけを動的に更新でき、パフォーマンスとキャッシュの効率を大幅に向上させています。 このように、BEAR.SundayとFastlyの統合によるROAベースのキャッシュ戦略は、高度な分散キャッシングの実現とともに、アプリケーションのパフォーマンス向上と耐障害性の強化を実現しています。これにより、ユーザーはどんな状況下でも一貫した応答性とデータ整合性を体験することができます。 -## テストの容易性 +### 起動の高速化 + +DIの本来の世界では、ユーザーは可能な限りインジェクター（DIコンテナ）を直接扱いません。その代わり、アプリケーションのエントリーポイントで1つのルートオブジェクトを生成してアプリケーションを起動します。BEAR.SundayのDIでは、設定時でもDIコンテナの操作が実質存在しません。ルートオブジェクトは巨大ですが1つの変数なのでリクエストを超えて再利用され極限まで最適化したブートストラップを実現します。 + +## 開発者エクスペリエンス + +### テストの容易性 BEAR.Sundayは、以下の設計上の特徴により、テストが容易で効果的に行えます。 @@ -142,34 +151,30 @@ BEAR.Sundayは、以下の設計上の特徴により、テストが容易で効 * ResourceObectには`header`メタ情報が含まれメタ情報によるテストが可能です。例えばキャッシュされているコンテンツであれば`Age`ヘッダーを確認することでキャッシュの有無をテストできます。MVCのモデルと比較してください。 * `#[Embed]`で埋め込まれたリソースは値ではなく、リソースのリクエストが埋め込まれます。どのようなリソースを埋め込むかの意図をテストできます。 -## リソースの検証 +### 視覚化とデバッグ -JsonSchemaを使用してリソースの表現を検証し、リソースの整合性を保ちます。バリデーションに標準のスキーマを使うことで外部ツールの利用ができます。 +* 開発時にHTML上でリソースの範囲やツールをグラフィカルに表示します。 +* Web画面でリソースの状態を確認でき、PHPコードやHTMLテンプレートをオンラインで編集し、リアルタイムに反映できます。 -## ストリーム出力 -* リソースの表現をストリーム出力することで、メモリ上では扱えない大規模なコンテンツを出力できます。 -* ストリームは通常の値のアサインと混在することができます。 +### APIドキュメント生成 -## 視覚化とデバッグ +コードからAPIドキュメントを自動生成します。コードとドキュメントの整合性を保ち、保守性を高めます。 -* 開発時にHTML上でリソースの範囲やツールをグラフィカルに表示します。 -* Web画面でリソースの状態を確認でき、PHPコードやHTMLテンプレートをオンラインで編集し、リアルタイムに反映できます。 +## 拡張性と統合 -## 起動の高速化 +### リソースの検証 -* 事前コンパイルにより依存生成のPHPコードを生成して最小限のブートストラップを実現します。 -* 理想的なDIの世界では起動の時に1度だけインスタンスを生成します。これをルートオブジェクトと呼びますがこのルートオブジェクトをキャッシュすることで、初期化を再利用しアプリケーションの起動を高速化します。 +JsonSchemaを使用してリソースの表現を検証し、リソースの整合性を保ちます。バリデーションに標準のスキーマを使うことで外部ツールの利用ができます。 -## PHPインターフェイスとSQL実行の統合 +### PHPインターフェイスとSQL実行の統合 BEAR.Sundayでは、PHPのインターフェイスを使って、データベースとのやり取りを行うSQL文の実行を簡単に管理できます。クラスを実装することなく、インターフェイスに直接SQLの実行オブジェクトを束縛することが可能です。これにより、コードの再利用性が向上し、モジュール性が強化されます。 - ### クエリー引数の評価 BEAR.Sundayのインターフェイスは、単なるスカラー値だけでなくオブジェクトも受け入れることができます。特に、オブジェクトがインターフェイスによってどのように評価されるかは重要です。例えば、DateTimeInterface オブジェクトをインターフェイスに渡すと、これがSQL文内で適切に日付として扱われるように自動的に評価されます。これにより、日付や時刻のデータを効率的に扱うことができます。 -### クエリーの引数の依存性注入 +#### クエリーの引数の依存性注入 BEAR.Sundayでは、インターフェイスに対して依存性を注入することも可能です。これにより、必要なオブジェクトや値を動的にインターフェイスに供給することができ、より柔軟なアプリケーション設計が実現されます。依存性注入を用いることで、コードのテストが容易になり、結合度を低く保ちつつ高い凝集度を維持することができます。 -### AIとツールを活用したSQL生成と最適化 +#### AIとツールを活用したSQL生成と最適化 BEAR.Sundayでは、インターフェイスに対して依存性を注入することも可能です。これにより、必要なオブジェクトや値を動的にインターフェイスに供給することができ、より柔軟なアプリケーション設計が実現されます。依存性注入を用いることで、コードのテストが容易になり、結合度を低く保ちつつ高い凝集度を維持することができます。 ### 総合的なデバッグとメンテナンスの利便性 @@ -179,17 +184,20 @@ SQLの直接管理は、エラー発生時のデバッグを容易にします * PHPのインターフェイスにはスカラー値だけでなくオブジェクトを指定して文字列として評価することもできます。例えばDateTimeInterfaceを指定すると、SQLの日付として評価されます。 * PHPインターフェイスには引数を依存性として注入することができます。 -## APIドキュメント生成 - -コードからAPIドキュメントを自動生成します。コードとドキュメントの整合性を保ち、保守性を高めます。 - -## 他システムとの統合 +### 他システムとの統合 * コンソールアプリケーションと統合し、ソースコードを変えずにWebとコマンドライン双方からアクセス可能にします * 同一PHPランタイム内で異なるアプリケーションを並行実行でき、HTTPクライアントから全リソースにアクセス可能にします。 * ローカル及びリモートのBEAR.Sundayアプリケーションを同様に扱え、BEAR.Thriftでは他言語のアプリケーションとも連携できます。 -## 標準への準拠 +### ストリーム出力 +* リソースの表現をストリーム出力することで、メモリ上では扱えない大規模なコンテンツを出力できます。 +* ストリームは通常の値のアサインと混在することができます。 + + +## 設計思想と品質 + +### 標準への準拠 * デフォルトでJSON形式とwwwフォーム形式をサポートし、コンテントタイプに応じてリソースリクエストを解釈します。 * セマンティックバージョンニングを採用し、後方互換性を維持します。 @@ -197,7 +205,7 @@ SQLの直接管理は、エラー発生時のデバッグを容易にします * リソースの状態変更時にETagを使用して、キャッシュを無効化します。 * キャッシュするとHTTPヘッダーに`Cache-Control`に加え`Ages`、`Last-Modified`。`ETag`などのHTTPヘッダーが付与されます -## オブジェクト指向原則 +### オブジェクト指向原則 BEAR.Sundayはアプリケーションを長期的にメンテナンス可能すとするためのオブジェクト指向原則を重視しています。 @@ -209,11 +217,7 @@ BEAR.Sundayはアプリケーションを長期的にメンテナンス可能す フレームワークのクラスが「設定ファイル」や「デバック定数」を実行中に参照して振る舞いを決定する事はありません。振る舞いに応じた依存が注入されます。これにより、アプリケーションの振る舞いを変更するためには、コードを変更する必要がなく、インターフェイスに対する依存性の実装の束縛を変更するだけで済みます。APP_DEBUGやAPP_MODE定数は存在しません。ソフトウエアが起動した後に現在どのモードで動いているか知る方法はありませんし、知る必要もありません。 -### ルートオブジェクト - -DIの本来の世界では、ユーザーは可能な限りインジェクター（DIコンテナ）を直接扱いません。その代わり、アプリケーションのエントリーポイントで1つのルートオブジェクトを生成してアプリケーションを起動します。BEAR.SundayのDIでは、設定時でもDIコンテナの操作が実質存在しません。ルートオブジェクトは巨大ですが1つの変数なのでリクエストを超えて再利用され極限まで最適化したブートストラップを実現します。 - -## 後方互換性の非破壊 +### 後方互換性の非破壊 BEAR.Sunday は、ソフトウェアの進化において後方互換性の維持を重視して設計されています。現代のソフトウェア開発では、頻繁な後方互換性の破壊と、それに伴う改修やテストの負担が課題となっていますが、BEAR.Sunday はこの問題を避けることを目指し成功しています。 @@ -225,7 +229,7 @@ BEAR.Sunday では、セマンティックバージョニングを採用し、 後方互換性の維持を絶対命題とした設計と、セマンティックバージョニングによるアプローチが、この長期的な互換性の維持を可能にしています。これにより、開発者は安心して BEAR.Sunday を採用し、進化するエコシステムの恩恵を受けることができるのです。 -## コード品質 +### コード品質 高いコード品質のアプリケーションを提供するためにBEAR.Sundayフレームワークも高い水準でコード品質を保っています。