Lagom參考指南（二）

1.Defining a Lagom build（定義一個Lagom構建）

正如在Lagom構建哲學中已經討論過的那樣，使用Lagom，您能夠自由地將全部服務組合在一個單獨的構建中，或者單獨構建它們。
下面，咱們將描述如何構建包含全部服務的單一構建。hello示例遵循這個結構。
而後，在下一節中，咱們將描述一個服務構建的替代方法。
（1）理解你的項目結構
    每一個服務至少包含兩個部分:一個API項目和一個實現項目。(這些是同一構建中的子項目。）
    API項目包含服務接口，也稱爲描述符，以及接口使用的全部數據模型，例如請求和響應消息。API項目能夠依賴於其餘服務的使用和使用。
    實現項目天然也依賴於API項目，以實現它。
    考慮下面的示例系統:
    ![圖片描述][1]
    這個系統有兩個服務，一個服務叫hello,另外一個服務叫hello-stream。每一個服務有兩個定義的sbt項目，一個api項目：hello-api和hello-stream-api，和一個實現項目：hello-impl和hellp-stream-impl.此外，hello-stream-impl依賴於hello-api，調用hello-stream來使用它。
    
    下面咱們將怎麼建立一個Lagom服務：
    ①配置項目根（Configuring the root project）
    在Lagom，使用多模塊構建是典型的。能夠在根項目中配置Lagom maven插件，咱們須要把它加到pom文件裏的plugins標籤裏：
        <plugin>
            <groupId>com.lightbend.lagom</groupId>
            <artifactId>lagom-maven-plugin</artifactId>
            <version>${lagom.version}</version>
        </plugin>
    這樣作將容許您使用像lagom:runAll這樣的命令來運行系統中的每個服務，並定義系統範圍的配置。Maven插件從父poms繼承它們的配置，所以在父pom中定義的任何東西都將用於全部服務。
    由於lagom是須要jdk1.8以上的，因此您須要將Java編譯的源和目標版本設置爲1.8。此外，Lagom自帶jackson參數拆箱。容許jackson將json反序列化爲沒有附加註釋元數據不可變的類。利用這個特性，Java編譯器必須啓用參數名稱。源、目標和參數名配置最好在根項目中配置，由於配置將由全部子模塊繼承：
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.5.1</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
                <compilerArgs>
                    <arg>-parameters</arg>
                </compilerArgs>
            </configuration>
        </plugin>
    咱們還建議在您的根項目pom中使用Maven依賴管理來控制整個系統中的依賴版本，例以下面：
        <dependencyManagement>
            <dependencies>
                <dependency>
                    <groupId>com.lightbend.lagom</groupId>
                    <artifactId>lagom-javadsl-server_2.11</artifactId>
                    <version>1.3.4</version>
                </dependency>
                <dependency>
                    <groupId>com.typesafe.play</groupId>
                    <artifactId>play-netty-server_2.11</artifactId>
                    <version>2.6.0-M5</version>
                </dependency>
                <dependency>
                    <groupId>com.lightbend.lagom</groupId>
                    <artifactId>lagom-javadsl-api_2.11</artifactId>
                    <version>1.3.4</version>
                </dependency>
            </dependencies>
        </dependencyManagement>
    關於Scala版本的註釋：
        在向Lagom庫中添加依賴關係時，您須要確保在工件ID中包含Scala主版本，for example：lagom-javadsl-api_2.11.Lagom自己是大多在Scala實現，與Java不一樣，Java維護者控制虛擬機，當添加新特性時，能夠在虛擬機上構建向後兼容性，當在Scala中添加新特性時，向後兼容性是很是困難的若是不是不可能維持，所以，必須根據Scala的某個主要版原本編譯庫。
        jar包的庫常常會想支持多個版本的Scala,這樣作須要構建一個爲每一個版本的Scala支持工件,它介紹瞭如何區分這些工件的問題,看到像maven不支持添加額外的元數據依賴關係的想法來指定他們須要什麼版本的Scala。爲了解決這個問題，咱們使用了將Scala版本附加到工件的約定。
        
    定義一個服務：
    服務的API模塊是一個簡單的maven項目。它不須要配置Lagom插件，一般它只須要依賴於Lagom API庫。例如:
        <project>
            <modelVersion>4.0.0</modelVersion>
            <parent>
                <groupId>com.example</groupId>
                <artifactId>my-first-system</artifactId>
                <version>1.0-SNAPSHOT</version>
            </parent>
        
            <artifactId>hello-api</artifactId>
        
            <packaging>jar</packaging>
        
            <dependencies>
                <dependency>
                    <groupId>com.lightbend.lagom</groupId>
                    <artifactId>lagom-javadsl-api_2.11</artifactId>
                </dependency>
            </dependencies>
        </project>
    服務的實現模塊也是一個簡單的maven項目，可是會有更多的依賴關係，而且須要配置 lagom-maven-plugin；來讓它成爲一個服務項目，因此這個插件知道在使用runAll時包含進它:
        <project>
            <modelVersion>4.0.0</modelVersion>
            <parent>
                <groupId>com.example</groupId>
                <artifactId>my-first-system</artifactId>
                <version>1.0-SNAPSHOT</version>
            </parent>
        
            <artifactId>hello-impl</artifactId>
        
            <packaging>jar</packaging>
        
            <dependencies>
                <dependency>
                    <groupId>${project.groupId}</groupId>
                    <artifactId>hello-api</artifactId>
                    <version>${project.version}</version>
                </dependency>
                <dependency>
                    <groupId>com.lightbend.lagom</groupId>
                    <artifactId>lagom-javadsl-server_2.11</artifactId>
                </dependency>
                <dependency>
                    <groupId>com.lightbend.lagom</groupId>
                    <artifactId>lagom-javadsl-persistence_2.11</artifactId>
                </dependency>
                <dependency>
                    <groupId>com.lightbend.lagom</groupId>
                    <artifactId>lagom-logback_2.11</artifactId>
                </dependency>
                <dependency>
                    <groupId>com.typesafe.play</groupId>
                    <artifactId>play-netty-server_2.11</artifactId>
                </dependency>
                <dependency>
                    <groupId>com.lightbend.lagom</groupId>
                    <artifactId>lagom-javadsl-testkit_2.11</artifactId>
                </dependency>
            </dependencies>
        
            <build>
                <plugins>
                    <plugin>
                        <groupId>com.lightbend.lagom</groupId>
                        <artifactId>lagom-maven-plugin</artifactId>
                        <configuration>
                            <lagomService>true</lagomService>
                        </configuration>
                    </plugin>
                </plugins>
            </build>
        </project>
    
    這裏有幾點須要注意:
        >實現依賴於它的API項目，所以它能夠實現這個API。
        >它也須要依賴於lagom-javadsl-server，這爲項目提供了全部服務器端代碼。
        >這個特別的服務使用Lagom的持久化API來對數據進行持久化，因此它還須要你依賴於lagom-javadsl-persistence.
        >日誌，默認的是使用lagom-logback作維護日誌的實現
        >play框架的 HTTP服務器的實現須要配置- Play提供兩個服務器實現，一個在Netty，一個在Akka HTTP。在這種狀況下，Netty已經被選中。
        >lagon-maven-plugin已經配置好了取讓lagonService是true，這告訴Lagom，這是一個在運行lagon:run時應該運行的Lagom服務

2.將一個系統分解爲多個構建

在設計一個Lagom系統時，您能夠靈活地組織您的服務，以構建知足您需求的構建單元。對於一個由單個團隊維護的小系統來講，在一個構建中擁有全部服務是很好的，這樣作使得使用runAll來運行全部的服務變得很是容易，咱們稍後將在本手冊的運行服務部分中看到：
若是您有多個團隊，那麼正如在Lagom構建概念中所描述的那樣，咱們建議將您的系統劃分爲多個構建。
若是您不關心擴展到多個團隊，如今能夠跳過這一部分。
（1）發佈服務
即便有多個版本,您仍然常常但願在開發中一塊兒運行您的服務。Lagom容許你從一個否到另一個構建的導入已經發布的服務。
假設您有一個hello服務，您想要發佈和導入另外一個構建。若是使用Maven，能夠經過運行mvn安裝，將其發佈到本地存儲庫，這是發佈服務的最簡單方法。然而，這意味着每一個想要運行構建版本的開發人員都須要將其發佈到本身的存儲庫中，他們須要爲他們想要導入的每一個版本作到這一點。
絕大多數狀況下，一些開發人員會分享一個單一供發佈於或者拉去項目用的的maven倉庫，若是您樂於使用託管存儲庫，那麼有一些方法能夠作到這一點，若是您想運行存儲庫位置， Artifactory 或Nexus是常見的解決方案
（2）導入服務
使用maven：
    Lagom-maven-plugin提供了一個配置項，叫作externalProjects，這個額配置項是能夠在根項目上配置，將外部項目導入Maven構建，例如：
        <plugin>
            <groupId>com.lightbend.lagom</groupId>
            <artifactId>lagom-maven-plugin</artifactId>
            <version>${lagom.version}</version>
            <configuration>
                <externalProjects>
                    <externalProject>
                        <artifact>
                            <groupId>com.example</groupId>
                            <artifactId>hello-impl</artifactId>
                            <version>1.2.3</version>
                        </artifact>
                    </externalProject>
                </externalProjects>
            </configuration>
        </plugin>
    那麼如今，當你運行lagom：runAll的時候，hello-impl服務也會被啓動起來，這裏還有一些externalProjects選項的其餘配置項
        >playService 代表這是一個play，而不是一個Lagom服務,默認值是false
        >servicePort 該服務所運行的端口號，默認的是經過Llagom來自動的選擇。
        >cassandraEnabled 配置該服務是否須要Cassandra，默認是true

3.將項目導入到IDE中，這個不翻譯了，太基礎了
4.使用maven和eclipse，建立一個Lagom的服務

maven 3.3以上
java 1.8
step1:File->new->Project
step2:other選項，找maven,建立maven project
step3:maven就用默認的選項就好了，也就是quick-start
step4:groupId啥的，很少說了
step5:run Project
      ①右鍵單擊父項目文件夾
      Eclipse將全部Maven項目文件夾放在相同的級別，因此必定要選一個正確的。例如：若是你要使用my-first-system做爲maven的 artifact ID，右鍵my-first-system
      ②run as..-> Maven Build
      ③Goal裏寫 lagom:runAll
      ④選擇jre
      ⑤run
  控制檯應該報告服務啓動。經過從任何HTTP客戶端調用hello服務端點(例如瀏覽器)來驗證服務是否確實啓動並運行。
  http://localhost:9000/api/hello/World
  請求返回消息:Hello, World!

5.在IDE中設置Immutable

Immutables是一個咱們建議來建立不可變對象的庫，並將樣板代碼減小到最小值。咱們相信您會找到這個庫，可是由於immutables從註釋中生成源，因此須要啓用Java編譯器註釋處理器。
Eclipse：
    要在Eclipse中設置Immutables註釋處理器，您須要爲每一個使用Immutables工具來生成不可變對象的項目配置如下內容。
    若是下面的選項你木有，就安裝。地址是http://download.eclipse.org/releases/juno，位置是在Programming Language裏的Eclipse java Development Toolss通常狀況下，eclipse默認都木有。
    Open project Properties > Java Compiler > Annotation Processing、
    本章建議本身看官網吧，這邊等個人STS能夠的時候再補上。

6.增長sbt和Maven的內存

在dev模式中的Lagom啓動全部的服務，並在一個JVM中啓動一些內部的Lagom服務。這樣基於你的JVM的設置可能會產生OutOfMemoryError。能夠經過增長內存來啓動Maven和sbt。
咱們建議您增長 Metaspace，最大大小和線程堆棧大小。，你可使用-Xss2M -XX:MaxMetaspaceSize=1024M這個配置來體改你的你內存大小。確切的值可能取決於您的硬件和代碼庫。
Maven下：
    你能夠從 Maven 開始使用 MAVEN_OPTS 環境變量的額外內存。命令以下：
        $ MAVEN_OPTS="-Xms512M -Xmx1024M -Xss2M -XX:MaxMetaspaceSize=1024M" mvn lagom:runAll
    在本例中，咱們將設置初始的JVM堆512Mb，最大堆的1024M，一個線程堆棧爲2M，最大的Metaspace大小爲2014M。
    若是在不一樣的項目中須要不一樣的設置，那麼在每次調用中聲明MAVEN_OPTS都是錯誤的，而且在全局上導出它是不可能的。您可能但願使用direnv來設置每一個項目的環境變量。