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标签里：
        
            com.lightbend.lagom
            lagom-maven-plugin
            ${lagom.version}
        
    这样做将允许您使用像lagom:runAll这样的命令来运行系统中的每一个服务，并定义系统范围的配置。Maven插件从父poms继承它们的配置，因此在父pom中定义的任何东西都将用于所有服务。
    因为lagom是需要jdk1.8以上的，所以您需要将Java编译的源和目标版本设置为1.8。此外，Lagom自带jackson参数拆箱。允许jackson将json反序列化为没有附加注释元数据不可变的类。利用这个特性，Java编译器必须启用参数名称。源、目标和参数名配置最好在根项目中配置，因为配置将由所有子模块继承：
        
            org.apache.maven.plugins
            maven-compiler-plugin
            3.5.1
            
                1.8
                1.8
                
                    -parameters
                
            
        
    我们还建议在您的根项目pom中使用Maven依赖管理来控制整个系统中的依赖版本，例如下面：
        
            
                
                    com.lightbend.lagom
                    lagom-javadsl-server_2.11
                    1.3.4
                
                
                    com.typesafe.play
                    play-netty-server_2.11
                    2.6.0-M5
                
                
                    com.lightbend.lagom
                    lagom-javadsl-api_2.11
                    1.3.4
                
            
        
    关于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库。例如:
        
            4.0.0
            
                com.example
                my-first-system
                1.0-SNAPSHOT
            
        
            hello-api
        
            jar
        
            
                
                    com.lightbend.lagom
                    lagom-javadsl-api_2.11
                
            
        
    服务的实现模块也是一个简单的maven项目，但是会有更多的依赖关系，并且需要配置 lagom-maven-plugin；来让它成为一个服务项目，所以这个插件知道在使用runAll时包含进它:
        
            4.0.0
            
                com.example
                my-first-system
                1.0-SNAPSHOT
            
        
            hello-impl
        
            jar
        
            
                
                    ${project.groupId}
                    hello-api
                    ${project.version}
                
                
                    com.lightbend.lagom
                    lagom-javadsl-server_2.11
                
                
                    com.lightbend.lagom
                    lagom-javadsl-persistence_2.11
                
                
                    com.lightbend.lagom
                    lagom-logback_2.11
                
                
                    com.typesafe.play
                    play-netty-server_2.11
                
                
                    com.lightbend.lagom
                    lagom-javadsl-testkit_2.11
                
            
        
            
                
                    
                        com.lightbend.lagom
                        lagom-maven-plugin
                        
                            true
                        
                    
                
            
        
    
    这里有几点需要注意:
        >实现依赖于它的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构建，例如：
        
            com.lightbend.lagom
            lagom-maven-plugin
            ${lagom.version}
            
                
                    
                        
                            com.example
                            hello-impl
                            1.2.3
                        
                    
                
            
        
    那么现在，当你运行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来设置每个项目的环境变量。