乐优商城(三十五)——订单微服务

目录

一、订单系统接口

1.1 Swagger-UI

1.1.1 什么是OpenApi

1.1.2 什么是Swagger

1.1.3 快速入门

1.2 测试接口

1.2.1 创建订单接口

1.2.2 生成ID方式

1.2.3 查询订单接口

1.2.4 更新订单状态

1.2.5 分页查询订单

1.2.6 生成微信付款链接

1.2.7 查询支付状态


一、订单系统接口

1.1 Swagger-UI

1.1.1 什么是OpenApi

随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、前后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。  前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要。

没有API文档工具之前,大家都是手写API文档的,在什么地方书写的都有,而且API文档没有统一规范和格式,每个公司都不一样。这无疑给开发带来了灾难。

OpenAPI规范(OpenAPI Specification 简称OAS)是Linux基金会的一个项目,试图通过定义一种用来描述API格式或API定义的语言,来规范RESTful服务开发过程。目前V3.0版本的OpenAPI规范已经发布并开源在github上 。

官网:https://github.com/OAI/OpenAPI-Specification

1.1.2 什么是Swagger

OpenAPI是一个编写API文档的规范,然而如果手动去编写OpenAPI规范的文档,是非常麻烦的。而Swagger就是一个实现了OpenAPI规范的工具集。

官网:https://swagger.io/

官方的说明:

Swagger包含的工具集:

  • Swagger编辑器: Swagger Editor允许您在浏览器中编辑YAML中的OpenAPI规范并实时预览文档。

  • Swagger UI: Swagger UI是HTML,Javascript和CSS资产的集合,可以从符合OAS标准的API动态生成漂亮的文档。

  • Swagger Codegen:允许根据OpenAPI规范自动生成API客户端库(SDK生成),服务器存根和文档。

  • Swagger Parser:用于解析来自Java的OpenAPI定义的独立库

  • Swagger Core:与Java相关的库,用于创建,使用和使用OpenAPI定义

  • Swagger Inspector(免费): API测试工具,可让您验证您的API并从现有API生成OpenAPI定义

  • SwaggerHub(免费和商业): API设计和文档,为使用OpenAPI的团队构建。

1.1.3 快速入门

SpringBoot已经集成了Swagger,使用简单注解即可生成swagger的API文档。

引入依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

编写配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .host("http://order.leyou.com")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.leyou.order.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("乐优商城订单系统")
                .description("乐优商城订单系统接口文档")
                .version("1.0")
                .build();
    }
}

接口声明

在controller的每个handler上添加接口说明注解:

package com.leyou.order.controller;

import com.leyou.common.pojo.PageResult;
import com.leyou.order.pojo.Order;
import com.leyou.order.service.OrderService;
import com.leyou.order.utils.PayHelper;
import com.leyou.order.utils.PayState;
import io.swagger.annotations.*;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import javax.validation.Valid;

/**
 * @Author: 98050
 * @Time: 2018-10-27 16:30
 * @Feature: 订单Controller
 */
@RestController
@Api("订单服务接口")
public class OrderController {

    @Autowired
    private OrderService orderService;

    @Autowired
    private PayHelper payHelper;

    /**
     * 创建订单
     * @param order 订单对象
     * @return 订单编号
     */
    @PostMapping
    @ApiOperation(value = "创建订单接口,返回订单编号",notes = "创建订单")
    @ApiImplicitParam(name = "order",required = true,value = "订单的json对象,包含订单条目和物流信息")
    public ResponseEntity<Long> createOrder(@RequestBody @Valid Order order){
        Long id = this.orderService.createOrder(order);
        return new ResponseEntity<>(id, HttpStatus.CREATED);
    }

    /**
     * 查询订单
     * @param id 订单编号
     * @return 订单对象
     */
    @ApiOperation(value = "根据订单编号查询订单,返回订单对象",notes = "查询订单")
    @ApiImplicitParam(name = "id",required = true,value = "订单编号")
    @GetMapping("{id}")
    public ResponseEntity<Order> queryOrderById(@PathVariable("id") Long id){
        Order order = this.orderService.queryOrderById(id);
        if (order == null){
            return ResponseEntity.status(HttpStatus.NOT_FOUND).build();
        }
        return ResponseEntity.ok(order);
    }

    /**
     * 分页查询当前已经登录的用户订单
     * @param page 页数
     * @param rows 每页大小
     * @param status 订单状态
     * @return
     */
    @GetMapping("list")
    @ApiOperation(value = "分页查询当前用户订单,并且可以根据订单状态过滤",notes = "分页查询当前用户订单")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "page",value = "当前页",defaultValue = "1",type = "Integer"),
            @ApiImplicitParam(name = "rows",value = "每页大小",defaultValue = "5",type = "Integer"),
            @ApiImplicitParam(name = "status",value = "订单状态:1未付款," +
                    "2已付款未发货," +
                    "3已发货未确认," +
                    "4已确认未评价," +
                    "5交易关闭," +
                    "6交易成功,已评价",defaultValue = "1",type = "Integer")
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "订单的分页结果"),
            @ApiResponse(code = 404, message = "没有查询到结果"),
            @ApiResponse(code = 500,message = "服务器异常")
    })
    public ResponseEntity<PageResult<Order>> queryUserOrderList(
            @RequestParam(value = "page",defaultValue = "1")Integer page,
            @RequestParam(value = "rows",defaultValue = "5")Integer rows,
            @RequestParam(value = "status",required = false)Integer status
    ){

        PageResult<Order> result = this.orderService.queryUserOrderList(page,rows,status);
        if (result == null){
            return new ResponseEntity<>(HttpStatus.NOT_FOUND);
        }
        return ResponseEntity.ok(result);
    }


    /**
     * 更新订单状态
     * @param id
     * @param status
     * @return
     */
    @PutMapping("{id}/{status}")
    @ApiOperation(value = "更新订单状态",notes = "更新订单状态")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "订单编号",type = "Long"),
            @ApiImplicitParam(name = "status",value = "订单状态:1未付款," +
                    "2已付款未发货," +
                    "3已发货未确认," +
                    "4已确认未评价," +
                    "5交易关闭," +
                    "6交易成功,已评价",defaultValue = "1",type = "Integer")
    })
    @ApiResponses({
            @ApiResponse(code = 204,message = "true:修改成功;false:修改状态失败"),
            @ApiResponse(code = 400,message = "请求参数有误"),
            @ApiResponse(code = 500,message = "服务器异常")
    })
    public ResponseEntity<Boolean> updateOrderStatus(@PathVariable("id") Long id,@PathVariable("status") Integer status){
        Boolean result = this.orderService.updateOrderStatus(id,status);
        if (result == null){
            //返回400
            return new ResponseEntity<>(HttpStatus.BAD_REQUEST);
        }
        //返回204
        return new ResponseEntity<>(result,HttpStatus.NO_CONTENT);
    }

    /**
     * 根据订单id生成付款链接
     * @param orderId
     * @return
     */
    @GetMapping("url/{id}")
    @ApiOperation(value = "生成微信扫描支付付款链接",notes = "生成付款链接")
    @ApiImplicitParam(name = "id",value = "订单编号",type = "Long")
    @ApiResponses({
            @ApiResponse(code = 200,message = "根据订单编号生成的微信支付地址"),
            @ApiResponse(code = 404,message = "生成链接失败"),
            @ApiResponse(code = 500,message = "服务器异常")
    })
    public ResponseEntity<String> generateUrl(@PathVariable("id") Long orderId){
        String url = this.payHelper.createPayUrl(orderId);
        if (StringUtils.isNotBlank(url)){
            return ResponseEntity.ok(url);
        }else {
            return ResponseEntity.status(HttpStatus.NOT_FOUND).build();
        }
    }

    /**
     * 查询付款状态
     * @param orderId
     * @return
     */
    @GetMapping("state/{id}")
    @ApiOperation(value = "查询扫码支付的付款状态",notes = "查询付款状态")
    @ApiImplicitParam(name = "id",value = "订单编号",type = "Long")
    @ApiResponses({
            @ApiResponse(code = 200, message = "0, 未查询到支付信息 1,支付成功 2,支付失败"),
            @ApiResponse(code = 500, message = "服务器异常"),
    })
    public ResponseEntity<Integer> queryPayState(@PathVariable("id") Long orderId){
        PayState payState = this.payHelper.queryOrder(orderId);
        return ResponseEntity.ok(payState.getValue());
    }


}

常用注解说明:

/**
 @Api:修饰整个类,描述Controller的作用
 @ApiOperation:描述一个类的一个方法,或者说一个接口
 @ApiParam:单个参数描述
 @ApiModel:用对象来接收参数
 @ApiProperty:用对象接收参数时,描述对象的一个字段
 @ApiResponse:HTTP响应其中1个描述
 @ApiResponses:HTTP响应整体描述
 @ApiIgnore:使用该注解忽略这个API
 @ApiError :发生错误返回的信息
 @ApiImplicitParam:一个请求参数
 @ApiImplicitParams:多个请求参数
 */

启动测试

启动服务,然后访问:http://localhost:8089/swagger-ui.html

访问过程中遇到到错误请参考:《坑》

点击order-controller,查看接口信息

点击任意一个接口,即可查看详细信息:

1.2 测试接口

1.2.1 创建订单接口

可以通过页面看到接口信息:

  • 请求方式:POST

  • 请求路径:/order

  • 请求参数:包含订单、订单详情等数据的json对象。

  • 返回结果:订单编号

点击Try It Out来测试

填入数据

{
  "totalPay": 236800,
  "postFee": 0,
  "paymentType": 2,
  "actualPay": 236800,
  "buyerMessage": null,
  "buyerNick": "huge",
  "orderDetails": [
    {
      "skuId": 3893493,
      "num": 1,
      "title": "苹果(Apple)iPhone 6 (A1586) 16GB 金色 移动联通电信4G手机3",
      "price": 236800,
      "ownSpec": "{\"机身颜色\":\"钻雕蓝\",\"内存\":\"4GB\",\"机身存储\":\"64GB\"}",
      "image": "http://image.leyou.com/images/9/4/1524297342728.jpg"
    }
  ],
  "receiver": "锋哥",
  "receiverMobile": "15800000000",
  "receiverState": "上海",
  "receiverCity": "上海",
  "receiverDistrict": "浦东新签",
  "receiverAddress": "航头镇航头路18号传智播客3号楼",
  "receiverZip": "210000",
  "invoiceType": 0,
  "sourceType":2
}

点击Execute

查看返回结果

401 未授权,因为下订单需要用户登录,所以要携带token。

通过登录生成token

把token的值手动加入到浏览器的cookie中

再次执行

添加成功,响应订单编号。

1.2.2 生成ID方式

请参考:《分布式自增id》

1.2.3 查询订单接口

接口说明

  • 请求方式:GET

  • 请求路径:/order/{id}

  • 请求参数:id,订单编号

  • 返回结果:Order,订单的json对象

测试

输入刚才生成的订单号:

结果:

1.2.4 更新订单状态

接口说明

  • 请求参数:PUT

  • 请求路径:/order/{id}/{status}

  • 请求参数:

    • id:订单编号,String类型,不能为空

    • status:订单状态,不能为空

  • 返回结果:null

测试

数据库中的数据:

修改:

结果:

数据库:

1.2.5 分页查询订单

接口说明

  • 请求方式:Get

  • 请求路径:/order/list

  • 请求参数:

    • page:当前页,Integer类型,默认为1

    • rows:每页大小,Integer类型,默认为5

    • status:订单状态,String类型,默认查询全部状态订单

  • 返回结果:PageResult 对象,包含下面属性:

    • total:总条数

    • items:当前页订单数组

      • 订单对象

测试

结果:

改造一下分页代码

 

1.2.6 生成微信付款链接

接口说明

  • 请求方式:Get

  • 请求路径:/order/url/{id}

  • 请求参数:id,订单编号

  • 返回结果:String类型,生成的微信支付链接

测试

结果:

微信支付工具

1.2.7 查询支付状态

接口说明

  • 请求方式: Get

  • 请求路径: /state/{id}

  • 请求参数: id,订单编号

  • 返回结果:0, 未查询到支付信息 1,支付成功 2,支付失败(查询失败,或者订单过期)

未付款

未付款时查询,测试:

结果:

付款

已付款

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值