现在基于SpringCloud的微服务开发日益流行，网上各种开源项目层出不穷。我们在实际工作中可以参考开源项目实现很多开箱即用的功能，但是必须要遵守一定的约定和规范。

本文结合我们实际的开发中遇到的一些问题整理出了一份微服务开发的实践规范，欢迎各位大佬拍砖指点。

Maven规范

1. 
   

2. 
   

   所有项目必须要有一个统一的parent模块

   
   

   所有微服务工程都依赖这个parent，parent用于管理依赖版本，maven仓库，jar版本的统一升级维护

   
   

   在parent下层可以有 core，starter，rate-limit 等自定义模块

   
   

3. 
   

4. 
   

   core 核心包的作用：

   
   

• 
  

• 
  

  以POJO形式约定各种开发规范；如BaseEntity，统一入参，返参

  
  

• 
  

• 
  

  各种二方、三方组件开箱即用AutoConfig；

  
  

• 
  

• 
  

  各种提高开发效率的帮助类等  XXXUtil

  
  

注意：core包所有依赖的scope必须是provided，避免传递依赖，同时配合Condition注解按条件加载Bean 如 @ConditionalOnClass(Ribbon.class)，@ConditionalOnBean(StringRedisTemplete.class)

1. 
   

2. 
   

   starter模块

   
   

   如果你每个服务都需要依赖10几个starter，可以建一个统一的starter模块帮他们统一依赖进来，管理依赖集，简化依赖

   
   

3. 
   

4. 
   

   rate-limit模块

   
   

   用于放置非通用的自开发组件

   
   

5. 
   

6. 
   

   正确区分Release版本 和 Snapshot版本

   
   

   说明：如果是Snapshot版本，那么在mvn deploy时会自动发布到快照版本库中，而使用快照版本的模块，在不更改版本号的情况下，直接编译打包时，Maven会自动从镜像服务器上下载最新的快照版本。

   如果是Release版本，那么在mvn deploy时会自动发布到正式版本库中，而使用正式版本的模块，在不更改版本号的情况下，编译打包时如果本地已经存在该版本的模块则不会主动去镜像服务器上下载。

   
   

   简而言之：

   
   

   Release : 正式版，有bug不能再继续使用这个版本号

   
   

   Snapshot：快照版，有bug可以继续使用同一版本号，可以自动升级，推荐使用

   
   

服务调用规范

1. 
   

2. 
   

   服务间通过引入sdk调用，服务消费者需要依赖生产者提供的api，配合snapshot方便升级

   
   

account
 account-api
 account-service

account-api 模块中放消费方需要用到的东西，api接口，vo，入参等...

public interface AccountApi {
    ...
}

account-service实现account-api提供的接口

@RestController
@Log4j2
@Api(tags = "用户接口")
@RequiredArgsConstructor(onConstructor = @__(@Autowired))
public class AccountController implements AccountApi {
    ...
}

1. 
   

2. 
   

   消费者通过feign调用生产者，直接集成生产者提供的接口并处理熔断

   
   

@Component
@FeignClient(name = "account-service",fallbackFactory = AccountClientFallbackFactory.class)
public interface AccountClient extends AccountApi {
    ...
}

@Component
public class AccountClientFallbackFactory implements FallbackFactory {

    @Override
    public AccountClient create(Throwable throwable) {
        AccountClientFallback accountClientFallback = new AccountClientFallback();
        accountClientFallback.setCause(throwable);
        return accountClientFallback;
    }

}

@Slf4j
public class AccountClientFallback implements AccountClient {
    @Setter
    private Throwable cause;

    @Override
    public ResultData getByCode(String accountCode) {
        log.error("查询失败,接口异常" ,cause);
        AccountDTO account = new AccountDTO();
        account.setAccountCode("000");
        account.setAccountName("测试Feign");
        return ResultData.success(account);
    }

}

Restful设计规范

一个 API 是一个开发者的 UI - 就像其他任何 UI 一样, 确保用户体验被认真的考虑过是很重要的！

restful接口可以使用以下两种格式：

1. 
   

2. 
   

   /版本/访问控制/域对象

   
   

3. 
   

4. 
   

   /版本/访问控制/域对象/动作

   
   

域对象需要遵循以下几条约束：

1. 
   

2. 
   

   域对象 用名词而非动词

   
   

3. 
   

4. 
   

   直接使用域对象名  使用/ticket而不是复数/tickets

   
   

5. 
   

6. 
   

   域对象关系表达   最大不超过2层，如/ticket/12/message

   
   

7. 
   

8. 
   

   需要正确区分 GET PUT POST DELETE 请求方法

   
   

9. 
   

10. 
    

    无法用名词 + 请求方法表述的可以扩展为 /域对象/动词  如 POST /user/login

    
    

在网关层对接口进行访问控制，访问控制的规则分为：

pb - public 所有请求均可访问

pt - protected 需要进行token认证通过后方可访问

pv - private 无法通过网关访问，只能微服务内部调用

df - default 网关请求token认证，并且请求参数和返回结果进行加解密

版本：

以微服务为力度，整个服务进行升级

例如，一个微服务有如下API

GET /v1/pb/user

POST /v1/pb/user

PUT /v1/pb/user

如果 POST /v1/pb/user需要升级，则需要将整个微服务 /v1 升级到 /v2，同时保证版本兼容的api老版本可以继续访问

GET /v2/pb/user 等价于 GET /v1/pb/user

POST /v1/pb/user 标记为已废弃

POST /v2/pb/user

PUT /v2/pb/user 等价于 PUT /v1/pb/user

代码实现：

1. 
   

2. 
   

   GET方式{version}可以是任意值，v1,v2均可，如：@GetMapping("/{version}/pb/user")

   
   

   
   

   
   

3. 
   

4. 
   

   POST方法强制使用 V1 ,并标记为已废弃，但是仍可使用

   
   

@Deprecated
@PostMapping("/v1/pb/user")

1. 
   

2. 
   

   POST {version}应是当前版本，只能是v2

   
   

@PostMapping("/{version}/pb/user")

网关

1. 
   

2. 
   

   可以不承担微服务鉴权功能，由自己服务实现（简单服务可以直接在网关层鉴权）
   网关鉴权与微服务鉴权的差异在我其他文章中有详细说明，可参考此文：微服务网关授权VS微服务授权

   
   

3. 
   

4. 
   

   需要实现访问控制权限，结合上文的Restful规范，屏蔽 /pv/** 等特殊请求

   
   

5. 
   

6. 
   

   需要实现灰度发布功能
   开发联调的时候需要将服务器流量导入到本地，结合nacos的元数据与请求头可实现服务实例的筛选。