# zhmd-api

**Repository Path**: liubao68/zhmd-api

## Basic Information

- **Project Name**: zhmd-api
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2019-03-08
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 接口使用说明

## 对于接口实现者(provider)
  * 依赖api对应的jar包

```
  <dependencies>
    <dependency>
      <groupId>com.icss.newretail</groupId>
      <artifactId>delivery-center-api-endpoint</artifactId>
    </dependency>
  </dependencies>
```

  * 实现Service接口
```
  @Service
  public class DeliveryTaskServiceImpl implements DeliveryTaskService
```

## 对于接口使用者(consumer)
  * 依赖service对应的jar包（只包含model和接口）

```
  <dependencies>
    <dependency>
      <groupId>com.icss.newretail</groupId>
      <artifactId>delivery-center-api-service</artifactId>
    </dependency>
  </dependencies>
```

  * 采用RCP方式调用
```
  @RpcReference(microserviceName = "delivery-center", schemaId = "deliveryTask")
  private static DeliveryTaskService deliveryTaskService
```

# REST接口常见争议问题和处理

## 查询接口参数很复杂

比如：

```
public List<Goods> queryGoodsByTags(String orgId, List<GoodsTag> tags)
```

当查询参数很复杂的时候，不建议采用query参数或者path参数。主要有如下原因：

* HTTP对于URL的长度有限制
* 复杂参数可能包含特殊字符，需要客户端在拼接URL的时候，进行URL转码，客户端开发者通常会遗漏。
* 对象无法和query参数进行合理的映射。
* query参数或者path参数会被proxy、web server等记录到日志里面，导致日志过大，或者造成敏感信息泄露。

对于复杂的查询操作，建议使用POST方法，相关复杂参数都封装为body。比如：

```
@PostMapping(path = "queryGoodsByTags")
public List<Goods> queryGoodsByTags(@RequestParam(name = "orgId") String orgId, @RequestBody List<GoodsTag> tags)
```

一般的，通过query传递参数的场景，尽可能要保证参数个数少，参数类型为基础类型（字符串、数字等）。参数比较多的场景采用POST来传参。

本项目的处理原则是“尽可能遵循HTTP REST语义，但是不盲目，以系统可靠优先”。

对于DELETE请求，也有类似的情况。在设计GET和DELETE方法时，建议都不使用body参数，尽管HTTP协议并没有强制要求不能使用body，但是由于历史因素，很多WEB服务器支持上会有问题，接口设计应该尽可能避免不必要的麻烦和陷阱。只在POST、PUT、PATCH方法中使用body参数。

## REST接口的Path是否包含操作

比如：下面的接口定义path是否包含deleteGoodsUnitConvertor。 

```
  @DeleteMapping(path = "deleteGoodsUnitConvertor")
  public ResponseBase deleteGoodsUnitConvertor(String goodsUnitConvertorId)
```

由于HTTP的方法POST/PUT/PATCH/GET/DELETE已经包含了增、改、查、删语义，path里面包含delete显得多余。不过由于项目的接口通常比较多，过多的思考接口语义反而增加了理解的难度。所以本项目path全部都包含了方法名字。包含名称有个好处，可以从URL中看出operation id，从而很简单的将URL和契约对应起来，方便查找。此外就是上面提到的原因，并不是所有的删除操作都一定对应于DELETE操作，出于系统可靠性、安全等方面考虑，可能使用POST/PATCH等代表查询或者删除操作。

## 多个对象参数

由于HTTP只能有一个body，所有多个对象参数需要包装为一个参数。 比如：

```
public ResponseBase inboundOrder(InboundOrder inboundOrder, Set<InboundOrderItem> inboundOrderItems)
```

封装为下面的REST接口定义：

```
  @PostMapping(path = "inboundOrder")
  public ResponseBase inboundOrder(@RequestBody InboundOrderRequest inboundOrderRequest) {
    return stockService.inboundOrder(inboundOrderRequest.getInboundOrder(), inboundOrderRequest.getInboundOrderItems());
  }
```

## 敏感信息不能采用query参数

Query参数可能被各种proxy、web server记录，因此对于用户敏感信息，不能使用query参数。 比如：

```
public ResponseBase rechargePrepaidCard(String cardId, double amount)
```

涉及到卡号和金额的数据，需要采用POST提交，参数存储在body。 虽然有些接口仅仅只是查询， 但也可能被设计为POST。 调整后的接口：

```
public ResponseBase rechargePrepaidCard(@RequestBody PrepaidAmountRequest prepaidAmountRequest)
```

# 项目介绍

* common-api  
各个项目共有的Model类

* ai-center  

* delivery-center 配送中心

配送中心主要提供商品配送相关的流程管理。比如生成配送单、领取配送单进行配送等。

* goods-center 商品中心

商品中心主要提供商品信息管理，包括录入商品、更新商品属性等。

* member-center 会员中心

会员中心主要提供会员的管理，包括增加会员、更新会员等级等。

* pay-center 支付中心

支付中心完成商品支付、结算、挂单、清单等功能。

* promotion-center 促销中心

促销中心完成促销信息录入，更新等功能。

* trade-center 

交易中心管理交易流程，比如购物车、入库出库等。

* user-center 用户中心

用户中心管理系统用户的角色、权限、菜单等信息。