微服务开发规范

时间:2021-07-05 20:09:13





创建微服务




微服务命名

微服务名称(service-name)采用三段式的命名规则,中间使用中横线分隔,即xxxx-xxxx-xxxx形式。


一级服务名为组织名称,如hope,二级服务名为应用或项目的名称,如madp,三级服务名为功能模块的名称,如auth。整体为hope-madp-auth
使用英文拼写,单词间不要使用空格和_。
请全部使用小写字母。


正例:
hope-madp-auth
hope-msp-ovp-order
反例:
hopemadp auth     [错误说明:格式错误]
hope_sd-madp-auth    [错误说明:空格,下划线]
hope-MADP-auth     [错误说明:大写]



微服务注册


开发微服务




项目配置(pom文件样例)


依赖及仓库配置

在项目的pom文件添加以下父依赖,用于实现微服务基础框架构建、健康检查、路由追踪等能力。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-sleuth</artifactId>
        </dependency>
        <!-- 健康检查-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        <!--客户端-->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-ribbon</artifactId>
        </dependency>
        <!--断路器-->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-hystrix</artifactId>
        </dependency>
        <!--服务发现客户端-->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-eureka</artifactId>
        </dependency>
        <!--远程配置客户端-->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-config-client</artifactId>
        </dependency>
        <!--zipkin集成-->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-sleuth-zipkin-stream</artifactId>
        </dependency>
    </dependencies>
  

groupId和artifactId命名

在pom文件中,请按照以下规则命名groupId和artifactId:


groupId:定义当前maven项目隶属的实际项目或应用,和微服务命名规范类似,按照组织-项目/应用进行命名,例如:hops-madp。
artifactId:请使用service-name,定义artifactId





服务配置

服务配置分为两部分,为本地配置和远程配置。

1.本地配置文件:bootstrap.yml。用来配置服务本身的属性,比如微服务名称,需要连接的配置服务器。

注意:本地配置中spring.application.name的值 = portal上填写的service-name

spring:
  application:
    name: service-name  # 应用名称必须保证全局唯一
  cloud:
    config:
      discovery:
        enabled: true
        service-id: config   # location of the configuration server
2.远程配置文件:{service-name}.yml。放在微服务平台的git仓库,用来配置业务逻辑中用到的配置信息。

注意:配置文件的文件名 = 本地配置中spring.application.name的值 = portal上填写的service-name
不同环境不同配置内容。

通用配置: {service-name}.yml


info:
  owner:
  description: your service's description!

server:
  port: {在微服务平台分配的范围内指定端口}

serviceConfig:
  url:





API设计


为便于管理,请按照格式将/service-name/apiName/v[1-9]+[0-9]*/作为Rest API的前缀
在RestControler中请勿添加/service-name


正例:
/service-name/apiName/v1/users/zhangsan/age
/service-name/apiName/v1/imgs/homepage/color
反例:
/apiName/v1/users/zhangsan/age               [错误说明:缺少service-name]
/service-name/v1/users/zhangsan/age          [错误说明:缺少apiName]
/service-name/apiName/1.2/users/zhangsan/age [错误说明:版本格式错误]



日志格式



路径:为方便日志收集,请将日志输出至路径/var/logs/msp/{service-name}.log,可以根据需要对日志文件进行切割。

格式:为方便日志分析,请按照以下格式生成日志,其中Exception字段可以不输出,也可以自定义其他日志。


{
    "service-name":"madp-auth",
    "apiName":"username_by_im_username",
    "AppKey":"",
    "ClientIp":"",
    "Server":"",
    "ServerPort":8081,
    "URI":"/madp-auth/login/users/username",
    "RequestMethod":"GET",
    "RequestParameters": ["",""],
    "Method":"userInfoByUserName",
    "ResponseStatus":200,
    "Exception":{
        "description":"service meet some mistakes",
        "error":"Internal Server Error"
    }
    "YourPrivateLogs":{

    }
}



部署微服务

您可以选择将微服务部署在您自行管理的服务器或微服务平台的服务器上。

如果希望部署在自行管理的服务器上,并且需要微服务平台提供的日志统计与分析、服务监控与守护等能力,需要开通服务器的账号以便微服务平台进行相关部署。