跳到主要内容

7.0架构及规范

工程结构​

工程名说明默认端口号
b2b2c主工程（父）无
config-server配置中心8888
framework基础框架无
shoptnt-core核心业务无
base-api基础业务api7000
buyer-api买家api7002
seller-api商家api7003
manager-api管理中心api7004
consumer消费者服务无

包名​

工程包名规范​

项包名
主包名cn.shoptnt
framework<mainpackage>.framework
shoptnt-core<mainpackage>.core
buyer-api<mainpackage>.buyer.api
seller-api<mainpackage>.seller.api
manager-api<mainpackage>.manager.api
consumer<mainpackage>.consumer
ucenter<mainpackage>.ucenter

shoptnt-core 包名规范​

业务包名
主包名cn.shoptnt.core
会员<mainpackage>.member
店铺<mainpackage>.shop
商品<mainpackage>.goods
商品全文检索<mainpackage>.goodssearch
交易<mainpackage>.trade
支付<mainpackage>.payment
售后<mainpackage>.aftersale
结算<mainpackage>.orderbill
统计<mainpackage>.statistics

API路径规范​

项包名
会员/member/*
店铺/shop/*
商品/goods/*
交易/trade/*
支付/payment/*
售后/aftersale/*
结算/orderbill/*
统计/statistics/*

注：在每个api服务中，上述业务路径是相同的

异常规范​

根据http状态判断业务是否正常

如果正常要求返回对象的Json

如果有异常返回异常的json

异常Json格式规范​

{
    "code": "100",
    "message": "无权访问"，
    "data": []
}
项类型是否必须说明
code字符是错误码，详见下面错误码规范
message字符是错误信息
data对象或数组否可能需要的数据

code 规范​

三位数字

每个模块code规范：

业务规范错误码类
系统级别000 - 099
会员100 - 199MemberErrorCode
店铺200 - 299ShopErrorCode
商品300 - 399GoodsErrorCode
交易400 - 499TradeErrorCode
支付500 - 599PaymentErrorCode
售后600 - 699AftersaleErrorCode
结算700 - 799OrderBillErrorCode
统计800 - 899StatisticsErrorCode
系统900 - 999SystemErrorCode

每个模块在开发过程中应记录 code 的说明在这里：《错误码对照表》

异常类​

系统内置了一些异常类供开发者处理异常

统一定义在：cn.shoptnt.framework.exception中

异常说明
NoPermissionException无权限异常，比如试图更新一个别人的账号的密码
ResourceNotFoundException资源找不到异常
ServiceException其它业务异常

其中ServiceException 供业务类处理异常使用

throw new ServiceException(GoodsErrorCode.E300.code(),"消息");

可以通过设置其data 属性来向前端输出 error json中的data

List list  = ...
throw new ServiceException(GoodsErrorCode.E300.code(),"消息",list);

可以通过设置其 status_code 来改变http 在status code:

ServiceException e  = new ServiceException(GoodsErrorCode.E300.code(),"消息");
e.setStatus_code(HttpStatus.BAD_REQUEST);
throw e;

参数规范​

1.严格遵守《shoptnt开发规范》

2.应使用阿里巴巴代码规约扫描插件进行扫描，做到新增的类，全部符合扫描通过

3.前端向服务器端传参使用蛇形规范如：

?user_id=1&user_name=wangfeng

注：shoptnt7.0实现了自动将蛇形参数转化为驼峰参数的机制，接收上述参数的controller用驼峰即可：

public String  login(Integer userId,String userName)

4.服务器端向前端输出json参数使用蛇形规范，如：

{
  "brand_id": 0,
  "goods_name": "string"
  "image_list":[]
}

5.客户端向服务器端传递分页参数规范为：

page_no=<当前页号>&page_size=<分页大小>

6.服务器端向客户端口传输分页结果规范为：

{
  "data": [
    {.. }
  ],
  "data_total": 0,
  "page_no": 0,
  "page_size": 0
}

7.带有分页的api 1）分页参数命名必须使用pageNo（页码）和pageSize（每页显示数量） 2）参数类型必须是引用类型Integer 3）不能使用封装对象接收分页参数

配置中心使用规则​

  1. 开发时启动本地配置中心config-server。
  2. 开发环境可以指向配置本地仓储，线上仓储名为config，可以下载到本地，作为配置文件的本地仓储。
  3. 配置本地仓储，需要进行git add . 和git commit -m操作，但不可push到线上。

详情可参照教程：配置中心教程。

验权机制​

7.0全部采用token验权，

其中seller-api要求的是seller权限

buyer-api要求提buyer的权限

manager-api要求的是 manager的权限

为了便于开发，直接在header中传递token:

Authorization:Bearer yourtoken

在配置文件中可设置token加密秘钥

shoptnt:
  #token加密秘钥，请务必更换此词串，且注意保密
  token-secret: tokensecret123456

token的获取​

详情请参考基于Token机制鉴权架构

注：以下是生成无限期token的方法，测试的时候使用更方便

如果要生成管理端的token需要增加账号对应的角色

public void test() {
  //新建买家用户角色对象
  Buyer buyer = new Buyer();
  //设置用户ID
  buyer.setUid(用户uid);
  //设置用户名称
  buyer.setUsername("用户名");
  //设置uuid
  buyer.setUuid("用户uuid");

  JwtTokenCreater tokenCreater = new JwtTokenCreater("token的秘钥");
  tokenCreater.setAccessTokenExp(Integer.MAX_VALUE);
  tokenCreater.setRefreshTokenExp(Integer.MAX_VALUE);
  //创建Token
  Token token = tokenCreater.create(buyer);
  System.out.println(token.getAccessToken());
}

当前用户的获取​

使用UserContext获取：

//获取买家
Buyer buyer  = UserContext.getBuyer();

//获取卖家
Seller seller =  UserContext.getSeller();

//获取管理员
Admin admin = AdminUserContext.getAdmin();

获取request（ any where）​

使用ThreadContextHolder获取：

HttpServletRequest request = ThreadContextHolder.getHttpRequest();

获取spring 上下文​

使用ApplicationContextHolder获取：

ApplicationContextHolder.getBean("beanName");