コンテンツにスキップ

ドキュメント

設計者向けのドキュメント作成/編集手順の説明です。

前提条件

ドキュメントサーバーのローカル実行

ドキュメントは MkDocs というプログラムを利用して HTML への変換とサーバー実行を行っています。
Docker と Visual Studio Code を利用する場合は細かい仕組みは何も考えずに行えるような仕組みにしています。

  1. ドキュメント用リポジトリ を Visual Studio Code で開く
  2. F5 (デバッグの開始) を実行
    • ブラウザが起動します (要 Google Chrome, Debugger for Chrome)

Tip

サーバーが起動しない場合は Docker for Windows を再起動して再度試してみましょう。
それでもダメならまわりの技術者にヘルプを求めてください。

ドキュメントの新規作成

ドキュメントは markdown 形式で記載します。
拡張子は .md .markdown が利用できますが、このプロジェクトでは .md で統一します。

  1. 任意の名前 (拡張子は .md ) でファイルを作成
    • サーバーが実行中であればブラウザが自動でリロードし追加したファイルがメニューに表示されます

Warning

ファイル名に & は含めないでください。
ローカルサーバーでは問題なく表示されますが、共有サーバー上では表示ができません。

Todo

markdown 記法の説明

シーケンス図の作成

シーケンス図 は PlantUML を利用して作成します。

  1. 任意の名前 (拡張子は .pu ) でファイルを作成
  2. 1 で作成したファイルに以下の内容を貼り付け
  3. Alt+D (カーソル位置のダイアグラムをプレビュー) を実行

```plantuml tab="シーケンス図" @startuml title 呼び出し順序 View ->> Application: Application ->> Domain: Domain ->> Infrastructure: Infrastructure ->> ExternalSystem: Infrastructure <<-- ExternalSystem: Domain <<-- Infrastructure: Application <<-- Domain: View <<-- Application: @enduml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
```plantuml tab="オブジェクト図"
@startuml
title プロジェクトの依存関係

' 共通
' object "Resource" as Resource
' Resource <.. View
' Resource <.. Application
' Resource <.. Domain
' Resource <.. Infrastructure
' Resource <.. DependencyInjection
' note bottom of Resource
'   Resource はすべてのプロジェクトから参照される。
' endnote

' aa
object "View" as View
object "Application" as Application
object "DependencyInjection" as DependencyInjection
object "Domain" as Domain
object "Domain.ServiceDefinition" as Domain.ServiceDefinition
object "Infrastructure" as Infrastructure
object "Infrastructure.ServiceDefinition" as Infrastructure.ServiceDefinition
object "Database" as Database
object "ExternalSystem" as ExternalSystem
object "ExternalSystem.ServiceDefinition" as ExternalSystem.ServiceDefinition

Application ..> DependencyInjection : <<call (initialize)>>
DependencyInjection ..> Domain.ServiceDefinition : <<refer>>
DependencyInjection ..> Domain : <<refer>>
DependencyInjection ..> Infrastructure.ServiceDefinition : <<refer>>
DependencyInjection ..> Infrastructure : <<refer>>

note left of DependencyInjection
  構成ファイルから Dependency Injection をするときに
  対象の Assembly を Load している必要がある。
  Application で行うと結合が強くなるため、
  Dependency Injection を行うためだけのプロジェクトを間に挟む。
endnote

Application ..> Domain.ServiceDefinition : <<call (gRPC)>>

Domain.ServiceDefinition <|.. Domain : <<implement>>
Domain ..> Infrastructure.ServiceDefinition : <<call (gRPC)>>

Infrastructure.ServiceDefinition <|.. Infrastructure : <<implement>>
Infrastructure .> Database : <<refer>>
Infrastructure ..> ExternalSystem.ServiceDefinition : <<call>>

ExternalSystem.ServiceDefinition <|.. ExternalSystem : <<implement>>

note right of ExternalSystem.ServiceDefinition
  ExternalSystem を呼び出すためのサービス定義と実装は
  他社にソースコードレベルでの公開が可能なよう分割する
endnote

note right of ExternalSystem
  ここで実際に ExternalSystem を呼び出す。
endnote


note bottom of View
  View はどのプロジェクトにも依存しない。
  Application へは http 経由で呼び出すため、
  プロジェクトの依存関係は存在しない。
endnote

' デバッグ用
' object "Domain.HttpGateway" as Domain.HttpGateway
' object "Infrastructure.HttpGateway" as Infrastructure.HttpGateway
' Domain.HttpGateway .> Domain.ServiceDefinition : <<refer>>
' Domain.HttpGateway .> Domain : <<call (http)>>
' Infrastructure.HttpGateway .> Infrastructure.ServiceDefinition : <<refer>>
' Infrastructure.HttpGateway .> Infrastructure : <<call (http)>>

@enduml

Todo

PlantUML 記法の説明


最終更新日: 2021-12-08 18:02:18
Back to top