JHipster翻譯資料(1)[原創翻譯]JHipster Domain Language (JDL)

本文翻譯自官網:https://jhipster.github.io/jdl/

功力有限，部分不會翻譯的地方直接寫譯文了。由於目前JHipster的資料還比較少，先找一些英文的資料翻譯翻譯。
上來就找JDL也是有原因的，JDL也算是JHipster的一點門檻了，基本上要在JHipster里創建功能背后的對象，最好使用這種方式，因為JHipster會根據JDL生成對應對象需要的一堆東西，包括不僅限於CRUD操作。在網上找一些簡單的例子可以知道如何創建簡單的實體和關系，但是實際項目使用，你肯定會想使用JDL，而不是那個問答界面，實際操作你也會發現，用問答操作太容易出錯了。

JHipster Domain Language (JDL)

JDL是JHipster的領域特殊語言(specific domain language).這種語言的目的是為了使用簡單和友好的語法在一個文件(也可以是多個文件)里描述實體以及他們的關系。

你可以使用在線的JDL-Studio(https://jhipster.github.io/jdl-studio/)這個IDE去創建JDL以及UML可視化圖像。你同時也可以用這個工具創建或者輸出或者分享你的JDL模型的URL。

你可以使用import-jdl 子生成器使一個JDL文件生成你想要的實體。使用這個自生成器的命令是yo jhipster:import-jdl your-jdl-file.jh。你也可以使用JHipster UML使一個JDL文件生成你想要的實體，使用這個工具的命令是在生成的JHipster應用目錄下運行jhipster-uml your-jdl-file.jh。 (JHipster UML也有專門的教程)

這些工具是使用實體子生成器的替代。設計這些工具的理念是使用可視化工具總是比使用經典Yeoman問答容易管理實體間的關系。

JDL項目是開源的，地址是https://github.com/jhipster/jhipster-core/。這個項目和JHipster一樣是開源項目 (Apache 2.0 License)。這個項目也可以作為節點庫來處理JDL。

（如果你喜歡這個項目，別忘了點星在github上。這句就不仔細翻譯了。。）

這是這篇文章的主要內容:

1. JDL Sample
2. How to use it
3. The language
   3.1 Entity Declaration
   3.2 Relationship Declaration
   3.3 Enumerations
   3.4 Blobs
   3.5 Option declaration
   3.6 Microservice-related options
4. Commenting
5. All the relationships
6. Constants
7. Annexes
8. Issues and bugs

JDL Sample

我們把Oracle的"人力資源"例子翻譯成了JDL，地址在這里https://github.com/jhipster/jhipster-core/blob/master/lib/dsl/example.jh。這個例子同時被加載為JDL-Studio的默認例子，見地址https://jhipster.github.io/jdl-studio/

How to use it

如果你想使用JHipster UML而不是import-jdl子生成器，你需要安裝這個工具，命令是運行npm install -g jhipster-uml。

你可以使用JDL文件去生成實體：

• 使用擴展名 '.jh'或者'.jdl'創建一個文件
• 使用JDL-STudio聲明你的實體和關系，然后從這個工具里下載你的文件
• 在JHipster生成的應用文件夾中，運行命令 yo jhipster:import-jdl my_file.jdl 或者 jhipster-uml my_file.jdl

然后，就好了！

如果你是團隊工作，那么你的文件可能有多個。這個運行命令可以指定多個文件，不需要把多個文件合為一個。命令如下yo jhipster:import-jdl my_file1.jh my_file2.jh 或者 jhipster-uml my_file1.jh my_file2.jh

如果你想把這些用在自己的項目里，你可以添加這個依賴在本地，命令為npm install jhipster-core --save。然后保存在你的package.json文件中。

The language

我們盡力讓語法對開發者友好，你可以使用這個語言進行三個事：

• 聲明實體以及其屬性
• 聲明實體之間的關系
• 聲明一些JHipster特定的選項

Entity declaration

實體聲明的語法如下：

entity <entity name> {
  <field name> <type> [<validation>*]
}

• <entity name> 是實體的名字
• <field name>是實體的字段屬性的名字
• <type>JHipster支持的字段屬性
• <validation>可選選項，字段是否進行校驗

支持的類型以及校驗如鏈接https://jhipster.github.io/jdl/#annexes。如果校驗需要一個值，在校驗后面簡單增加(<value>)即可。

這是一個JDL代碼的例子：

entity A
entity B
entity C {}
entity D {
  name String required,
  address String required maxlength(100),
  age Integer required min(18)
}

因為JDL設計理念是簡單使用和簡單可讀，如果你的實體是空的(沒有字段)，你可以直接聲明一個實體使用entity A 或者 entity A {}.

注意：JHipster會增加一個默認的id字段，所以你不用擔心這個字段。

Relationship declaration

關系多的聲明語法如下：

relationship (OneToMany | ManyToOne | OneToOne | ManyToMany) {
  <from entity>[{<relationship name>}] to <to entity>[{<relationship name>}]
}

• (OneToMany | ManyToOne| OneToOne | ManyToMany)是關系的類型
• <from entity>是擁有此關系的實體擁有者：the source
• <to entity>是這個關系連接到的實體名字:the destination
• <relationship name> is the name of the field having the other end as type（不會翻、、請大俠賜教，個人理解這個就是對應關系的一個名字，這個名字可以任意起的，這個名字后面加小括號指定這個關系指定的字段）
• required注入的字段是否是必須的。

下面是一些簡單的例子：
一個BOOK有一個，必須的，Author，一個Author有幾本Books。

entity Book
entity Author

relationship OneToMany {
  Author{book} to Book{writer(name) required}
}

當然，在實際例子中，你會有一大堆關系，總是寫同樣的三行會很無聊。所以你可以這么聲明：

entity A
entity B
entity C
entity D

relationship OneToOne {
  A{b} to B{a},
  B{c} to C
}
relationship ManyToMany {
  A{d} to D{a},
  C{d} to D{c}
}

默認，連接使用id字段，但是你可以連接使用其他字段，所以你可能會這么寫

entity A {
  name String required
}
entity B


relationship OneToOne {
  A{b} to B{a(name)}
}

Enumerations

使用JDL的Enum的語法如下：

• 在文件中聲明一個枚舉:

enum Language {
    FRENCH, ENGLISH, SPANISH
    }

- 在一個實體中，增加一個字段用枚舉作為類型::

entity Book {
    title String required,
    description String,
    language Language
    }

Blob (byte[])

JHipster給予你很大的自由，可以選擇一個圖片類型或者任何二進制類型。JDL讓你一樣得到這些東西:僅僅使用編輯器創建一個慣例類型(見DataType)，使用下面的約定來命名：

• AnyBlob或者僅僅Blob去創建一個任意二進制類型
• ImageBlob創建一個圖片類型的字段
• ImageBlob 創建一個CLOB的字段(long text)

Option declaration

在JHipster，你可以為你的實體指定特殊選項，例如分頁或者DTO。你可以使用JDL做同樣的事：

entity A {
  name String required
}

entity B {}

entity C {}

dto A, B with mapstruct

paginate A, C with infinite-scroll
paginate B with pager

service A with serviceClass
service C with serviceImpl

語法中的關鍵字dto, paginate, service 及 with就是為了支持這些特性。如果錯誤的選項被指定，JDL會報紅色錯誤信息，並且會忽略這個選項，以保證不損壞JHipster的JSON文件

Service option

如果沒有指定services會創建一個資源類直接調用庫接口。這是默認和最簡單的設置，見A。Service with serviceClass (see B) will make the resource call the service class which will call the repository interface. Service with serviceImpl (see C) will make a service interface which will be used by the resource class.接口implenment了一個impl類，這個類將會call repository interface。

如果不確定是否需要service，可以使用默認的設置，對CRUD是ok的。如果你有很多業務邏輯，要使用很多庫，比較理想就是創建一個service類了。JHipster不推薦不必要的接口，但是如果你需要，你就建繼承impl的service類。

entity A {}
entity B {}
entity C {}

// no service for A
service B with serviceClass
service C with serviceImpl

JDL也支持多選項設置：

entity A
entity B
...
entity Z

dto * with mapstruct
service all with serviceImpl
paginate C, with pager

注意 *和all是等價的。最新版本還引進了排除語法(這個語法對於設置所有實體的選項時很有用)

entity A
entity B
...
entity Z

dto * with mapstruct except A
service all with serviceImpl except A, B, C
paginate C, with pager

在JHipster里，你可以選擇是否不要一些客戶端代碼，或者服務端代碼。即使你想添加一些后綴對Angular相關的文件，你都可以這么做。在JDL，你也可以

entity A
entity B
entity C

skipClient for A
skipServer for B
angularSuffix * with mySuperEntities

最后，表名也可以指定，這樣實體的名字和表名可以不一樣，默認實體的名字就是表的名字。

entity A // A is the table's name here
entity B (the_best_entity) // the_best_entity is the table's name

Microservice-related options

JHipster V3，可以創建微服務。你可以指定一些選項在JDL中生存你想要的實體:微服務的名稱，搜索引擎。指定微服務的名字的例子：

entity A
entity B
entity C

microservice * with mysuperjhipsterapp except C
microservice C with myotherjhipsterapp
search * with elasticsearch except C

第一種選項時用來告訴JHipster，你的微服務如何處理你的實體，第二種是指定你想使用的搜索引擎。

Commenting & Javadoc

可以給JDL文件添加Javadoc & comments。

和Java一樣，下面的例子說明如何添加:

/**
 * Class comments.
 * @author The JHipster team.
 */
entity MyEntity { // another form of comment
  /** A required attribute */
  myField String required,
  mySecondField String // another form of comment
}

/**
 * Second entity.
 */
entity MySecondEntity {}

relationship OneToMany {
  /** This is possible too! */
  MyEntity{mySecondEntity}
  to
  /**
   * And this too!
   */
  MySecondEntity{myEntity}
}

這些注釋會被JHipster自動加為Javadoc comments。

JDL處理自己的注釋如下：

// an ignored comment
/** not an ignored comment */

//開頭的注釋被人是JDL的注釋，不會被轉換為Javadoc。

注意JDL Studio 指定以#開頭也會忽略。

另一種形式的注釋如下：

entity A {
  name String /** My super field */
  count Integer /** My other super field */
}

這里A的name會被注釋為 My super field,第二個字段會注釋為My other super field。逗號是不強制使用的，但是你要注意不要因為逗號出問題：

entity A {
  name String, /** My comment */
  count Integer
}

這里A的name不會有注釋，而count會。

All the relationships

解釋如何使用JDL創建關系。

One-to-One

定義一個雙向關系，例如車有一個司機，司機有一個車。

entity Driver {}
entity Car {}
relationship OneToOne {
  Car{driver} to Driver{car}
}

一個單向的例子，Citizen有一個Passpport，但是Passport沒有權限獲知他的擁有者。

entity Citizen {}
entity Passport {}
relationship OneToOne {
  Citizen{passport} to Passport
}

One-to-Many

一個雙向的例子，Owner有沒有，一個或者多個Car對象，Car知道自己的擁有者。

entity Owner {}
entity Car {}
relationship OneToMany {
  Owner{car} to Car{owner}
}

JHipster不支持這個關系單向的情況，但是如果有，會長這樣

entity Owner {}
entity Car {}
relationship OneToMany {
  Owner{car} to Car
}

Many-to-One

One-to-Many 關系倒過來和前面一樣。這種關系單向的例子，例如Ca知道自己的擁有者

entity Owner {}
entity Car {}
relationship ManyToOne {
  Car{owner} to Owner
}

Many-to-Many

最后這個例子，Car知道自己的擁有者，Driver對象可以獲取自己的cars。

entity Driver {}
entity Car {}
relationship ManyToMany {
  Car{driver} to Driver{car}
}

注意擁有關系的對象，在to的左邊。

Constants

對於JHipster Core v1.2.7，JDL支持數值型常量。例子:

DEFAULT_MIN_LENGTH = 1
DEFAULT_MAX_LENGTH = 42
DEFAULT_MIN_BYTES = 20
DEFAULT_MAX_BYTES = 40
DEFAULT_MIN = 0
DEFAULT_MAX = 41

entity A {
  name String minlength(DEFAULT_MIN_LENGTH) maxlength(DEFAULT_MAX_LENGTH)
  content TextBlob minbytes(DEFAULT_MIN_BYTES) maxbytes(DEFAULT_MAX_BYTES)
  count Integer min(DEFAULT_MIN) max(DEFAULT_MAX)
}

Annexes

Here is the types supported by JDL:

SQL	MongoDB	Cassandra	Validations
String	String	String	required, minlength, maxlength, pattern
Integer	Integer	Integer	required, min, max
Long	Long	Long	required, min, max
BigDecimal	BigDecimal	BigDecimal	required, min, max
Float	Float	Float	required, min, max
Double	Double	Double	required, min, max
Enum	Enum		required
Boolean	Boolean	Boolean	required
LocalDate	LocalDate		required
		Date	required
ZonedDateTime	ZonedDateTime		required
		UUID	required
Blob	Blob		required, minbytes, maxbytes
AnyBlob	AnyBlob		required, minbytes, maxbytes
ImageBlob	ImageBlob		required, minbytes, maxbytes
TextBlob	TextBlob		required, minbytes, maxbytes

Issues and bugs

JDL的github連接:https://github.com/jhipster/jhipster-core

JHipster貢獻指南:https://github.com/jhipster/generator-jhipster/blob/master/CONTRIBUTING.md

提交issue和Requsts請使用我們的項目

• JDL issue tracker ：https://github.com/jhipster/jhipster-core/issues
• JDL Pull Requests ：https://github.com/jhipster/jhipster-core/pulls

請盡量精確你的問題：

• 一個Post必須只有一個問題，或者一個需求。
• 提需求是ok的，但是指派的任務必須是足夠原子的，且可以被理解