微服务开发手册.docx

1、微服务开发手册1 开发说明 所有服务均基于 spring boot 框架开发。Spring boot 内嵌了 tomcat 服务器，无需生成war 包，并简化了 maven 配置，能够让开发者快速入手 spring 的开发。 服务的接口定义需严格符合 restful 规范。rest 规范参考第 2 节 rest api 接口规范 所有服务都需要在注册服务上注册， 否则不能被其他服务所调用。 同时平台也能够实时监测服务的状态，能够及时预警及调度资源。 所有服务的配置信息统一保存于 gitlab 上，并通过配置服务获取配置。 对数据库的操作统一采用 MyBatis 框架。MyBatis 是个支持普

2、通 SQL 查询，存储过程和高级映射的优秀持久层框架。Spring boot 也提供了 mybatis 的集成方案，可以很快捷地整合 mybatis 到项目中。 包名约定：所有包均以 com.drht. 服务名 为父包名 ，如 com.drht.auth，后面再跟具体模块名称作为子包名。 所有项目基于 jdk1.8 来开发。项目的管理与构建采用 maven，代码统一托管于 gitlab仓库。2 rest api 接口规范spring boot 接口设计需符合 restful 风格。在 RESTful 架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的

3、名词往往与数据库的表格名对应。 而客户端要执行某种类型的操作，需要根据 http 的操作协议来决定。 HTTP 提供了常用的几种操作，如下表：动作 说明GET（SELECT） 从服务器取出资源（一项或多项）POST（CREATE ） 在服务器新建一个资源。PUT（UPDATE） 在服务器更新资源（客户端提供改变后的完整资源）。PATCH（UPDATE） 在服务器更新资源（客户端提供改变的属性）。DELETE（DELETE） 从服务器删除资源。对数据库的增删改查操作，应该严格遵守上面定义的五种 HTTP 动作。对于更新动作，参数通过 requestbody 来传递，格式为 json。服务端返回数

4、据格式也均为 json。服务端返回数据对象约定：public class UnifyInfo private int code; /返回代码，1 ：成功，0：失败private String message;/返回信息提示private String prompt;/private String path;/一般用于错误时的跳转路径private HashMap attribute;/一般用于 查询时的返回数据内容Spring boot 会自动将符合 javabean 格式的对象转换为 json 格式数据返回。示例：客户端请求 请求参数 服务端返回数据 说明GET /users “code“:

5、“1“,“message“:“查询成功“,“prompt“:“,“path“:“,“users“:查询所有用户GET /users/ID “code“:“1“,“message“:“查询成功“,“prompt“:“,“path“:“,“users“:查询指定 ID的用户POST /users “username“:“user2“,“email“:““code“:“0“,“message“:“创建用户失败“,“prompt“:“该用户已经存在“,“path“:“http:/localhost:8080/users“,“result“:创建一个用户PUT /users/ID “username“:

6、“user2“,“email“:““code“:“1“,“message“:“创建用户成功“,“prompt“:“,“path“:“,“result“:更新某用户信息PATCH /users/ID“username“:“user2“,“email“:““code“:“1“,“message“:“更新成功“,“prompt“:“,“path“:“,“result“:更新某用户指定字段DELETE /users/ID“code“:“1“,“message“:“删除成功“,“prompt“:“,“path“:“,“result“:删除指定用户而对于登录、登出操作，可以理解为登录是创建 token,登

7、出是删除 token,所以可以用POST 和 DELETE 来定义这两种接口。刷新 token 是更新操作所以用 PUT。3 配置文件管理所有服务的配置文档均保存于 gitlab 上，并通过配置服务 config-service 来获取配置。每个服务在 gitlab 均保存一份以服务 id 命名的 properties 文件。以服务 spring-boot-demo 为例 ，其在 gitlab 上的配置文件为 spring-boot-demo.properties ，文件名对应于该服务的 bootstrap.properties 中配置的spring.application.name 的 va

8、lue 值。如果名称不一致，配置服务将拿不到正确的配置信息。在 spring-boot-demo.properties 中通常配置该服务的启动端口、数据库连接参数等信息。 当该文件有更新并 push 到 gitlab 后，配置服务会自动通知客户端服务更新配置信息。关键配置：在主程序中需要访问配置文件的类名上加上注解：RefreshScope，如果没有该注解，配置服务将不能主动通知客户端服务更新配置。 如下：RefreshScopeRestControllerpublic class MessageRestController Value(“$message:Hello default“)pri

9、vate String message;RequestMapping(“/message“)String getMessage() return this.message;当 spring-boot-demo.properties 文件里的 message 变量发生变化后，请求 /message 时返回的message 值将是更新后的 message 内容。pom.xml 关键依赖项：org.springframework.cloud spring-cloud-config-client org.springframework.bootspring-boot-starter-actuator同

10、时需要引入 spring cloud 的依赖项org.springframework.cloudspring-cloud-dependenciesCamden.SR5pomimport在 src/main/resouce 目录建立 bootstrap.properties 文件，设置配置服务 url 与service id。bootstrap.properties 文件内容：#配置服务地址spring.cloud.config.uri =http:/172.168.4.43:9999#service namespring.application.name=spring-boot-demo注：不

11、能在 application.properties 设置配置服务的 url,因为 application.properties的启动优先级最低，不能在程序启动之前读取到配置服务 url,从而不能加载配置服务上相应的配置。4 服务注册register-service 提供服务的注册与发现。所有的服务都需要注册到 register-service 中，否则不能够被其他服务发现与调用，比如路由服务。关键配置pom.xml 关键依赖项：org.springframework.cloudspring-cloud-starter-eureka-server同时需要引入 spring cloud 的依赖项o

12、rg.springframework.cloudspring-cloud-dependenciesCamden.SR5pomimport主程序加上注解：EnableEurekaServer 如下：EnableEurekaServerSpringBootApplicationpublic class RegisterServiceApplication public static void main(String args) SpringApplication.run(RegisterServiceApplication.class, args);对应配置服务器上的 spring-boot-de

13、mo.properties 中添加注册服务的地址。spring-boot-demo.properties 配置如下：#服务启动端口server.port=8082#注册服务地址eureka.client.serviceUrl.defaultZone=http:/172.168.4.43:9998/eureka/5 统一网关路由所有 rest 请求均需要通过网关来路由到具体的服务。网关服务能起到负载均衡、动态路由、统一认证等功能。使用代理服务能够避免必须的跨域资源共享（Cross-Origin Resource Sharing）。当一个 UI 应用调用一个或更多的后端服务的时候，通过网关服务来做

14、统一的代理。前端应用不再需要关心后台业务服务的具体地址，因此当业务服务的地址变更后也不需要修改应用端的配置。 所有的请求都在网关做了统一的认证授权，因此业务服务也不再需要考虑与授权有关的问题。按照约定, 一个 serviceid 为“userservice“ 的服务会收到 /userservice 请求路径的代理请求(前缀会被剥离 )。因此要查询用户 ID 是 590d38b064328b1aac828ae6 的信息，完整的请求路径是http:/:/userservice/users/590d38b064328b1aac828ae6其中 userservice 是 user service 的

15、 sericeid,users/id是该服务提供的对外访问接口。网关服务会自动根据请求路径里的 serviceid（本例中是 userservice）找到userservice 的请求地址，并路由给该服务的 users/id接口，其最终的路由地址是http:/:/users/590d38b064328b1aac828ae6。注：url 不包括/userservice。而网关服务能够正确路由的前提是 userservice 已经在注册服务上注册。6 认证授权对于某用户的授权分为两类，一类是该用户是否能够访问某些 url,一类是它在界面上所能看到哪些功能（即菜单）。应用端访问后台服务时均需要经过授

16、权服务 auth-service 认证才能访问服务的资源。授权服务对资源的访问控制通过 uri + serviceid + HTTP METHOD 来控制，如角色 ROLE_USER 的资源权限为服务名为 userservice 的 user/*, 请求方式为 ALL ,则其对所有 userservice 服务的 uri 为 user/形式的资源均有权访问。如POST http:/:/user/add GET http:/:/user/query 所以在设计 api 接口时，需严格按照第一节中 rest api 的规范定义接口，以方便对某一类资源的请求做统一的权限配置。同时在应用端，某用户登录

17、进来后能够访问的菜单也是通过授权服务控制。菜单资源包括菜单的名称，图标，跳转路径等属性。应用端通过授权得到的菜单属性，并决定菜单界面的布局。菜单对象定义如下：public class Menu private Integer id;private String menuname;private Integer parentid;private String menucode;private String menuurl;private String menuicon;private String urltarget;private Integer isactive;private Intege

18、r navmenu;private Integer isleaf;private Integer viewtype;private Integer sort;private String remark;private String creator;private String modified;private Date createtime;private Date lastupdate;7 持续集成项目开发完成后，通过 jenkins 持续集成，打包成 docker 镜像后上传到服务器上的docker repository 后运行，所以需要在 pom.xml 文件里配置 maven docker 插件。Pom.xml 关键配置：src/main/resources