Skip to content
大纲

接口设计说明书 ​

Java后台接口 ​

R.java 后台接口返回类

接口返回参数 ​
java
// 返回标记:成功=0,失败=1
private int status;
// 返回信息
private String message;
// 数据
private T data;

接口返回方法 ​
方法返回http状态方法返回参数描述
ok200数据、状态及异常编码正常
failed400数据、状态及异常编码请求发生错误
unauthorized401数据、状态及异常编码认证异常
forbidden403数据、状态及异常编码没有权限
notFound404数据、状态及异常编码请求资源不存在
unprocessableEntity422数据、状态及异常编码请求数据异常

Vue接口 ​

Vue axios请求接口 ​
javascript
// 后台返回状态信息
const status = Number(res.status) || 200;
// 后台返回描述信息
const message = res.data.msg || errorCode[status] || errorCode['default']

// 后台定义 424 针对令牌过期的特殊响应码
if (status === 424) {
  ElMessageBox.confirm('令牌状态已过期,请点击重新登录', '系统提示', {
    confirmButtonText: '重新登录',
    cancelButtonText: '取消',
    type: 'warning'
  }).then(() => {
    store.dispatch('LogOut').then(() => {
      window.location.reload()
    })
  }).catch(() => {})
  return
}

// 正常返回
if (status !== 200 || res.data.code === 1) {
  if (status === 400) {
    ElMessageBox({
      message: i18nMessageJsons[res.data.message] || i18nMessageJsons['common_message_badRequest'],
      type: 'error'
    })
    return Promise.reject(new Error(i18nMessageJsons['common_message_badRequest']));
  }
// 认证异常
  if (status === 401) {
    ElMessageBox({
      message: i18nMessageJsons['common_message_unauthorized'],
      type: 'error'
    })
    return Promise.reject(new Error(i18nMessageJsons['common_message_unauthorized']));
  }
// 没有权限
  if (status === 403) {
    ElMessageBox({
      message: i18nMessageJsons['common_message_forbidden'],
      type: 'error'
    })
    return Promise.reject(new Error(i18nMessageJsons['common_message_forbidden']));
  }
// 请求资源不存在
  if (status === 404) {
    ElMessageBox({
      message: i18nMessageJsons['common_message_notFound'],
      type: 'error'
    })
    return Promise.reject(new Error(i18nMessageJsons['common_message_notFound']));
  }
// 请求数据异常
  if (status === 422) {
    ElMessageBox({
      message: i18nMessageJsons['common_message_unprocessableEntity'],
      type: 'error'
    })
    return Promise.reject(new Error(i18nMessageJsons['common_message_unprocessableEntity']));
  }
// 服务访问异常
  if (status === 503) {
    ElMessageBox({
      message: i18nMessageJsons['common_message_serviceUnavailable'],
      type: 'error'
    })
    return Promise.reject(new Error(i18nMessageJsons['common_message_serviceUnavailable']));
  }
// 服务器内部异常
  if (status === 500) {
    ElMessageBox({
      message: i18nMessageJsons['common_message_internalServerError'],
      type: 'error'
    })
    return Promise.reject(new Error(i18nMessageJsons['common_message_internalServerError']));
  }
// 其他异常
  ElMessageBox({
    message: i18nMessageJsons[message],
    type: 'error'
  })
  return Promise.reject(new Error(message))
}
return res
}, error => {
  NProgress.done()
  return Promise.reject(new Error(error))
})

管理平台接口js请求参数说明 ​
请求方式参数后台接收参数示例
GETparams : json参数普通类型 Integer、String ...String id、Integer sort
GET/' + id@PathVariable("id") String Id@PathVariable("userId") String userId
POSTdata : 对象@RequestBody Objuec obj@RequestBody Goods
goods
POSTparams : json参数普通类型 Integer、String ...String id、Integer sort
PUTdata : 对象@RequestBody Objuec obj@RequestBody Goods
goods
PUTparams : json参数普通类型 Integer、String ...String id、Integer sort
DELETEparams : json参数普通类型 Integer、String ...String id、Integer sort
DELETE/' + id@PathVariable("id") String Id@PathVariable("userId") String userId

Uni-app接口 ​

Uni-app请求接口 ​
javascript
uni.request({
			method: method,
			url: baseURL + url + paramsStr,
			data: data,
			header: headers,
			responseType: responseType,
			success: (res) => { //数据获取成功
				uni.hideLoading();
				const status = Number(res.status) || 200;
				const message = res.data.message || errorCode[status] || errorCode['default'];
				// 正常返回
        if (status != 200) {
					if (status === 400) {
						return uni.showToast({
							title: i18nMessageJsons[message] ||
								i18nMessageJsons['common_message_badRequest'],
							duration: 5000,
							icon: 'none'
						})
					}
          // 认证异常
					if (status === 401) {
						uni.reLaunch({
							url:"../../pages/index/login"
						})
					}
          // 没有权限
					if (status === 403) {
						return uni.showToast({
							title: i18nMessageJsons[message] || i18nMessageJsons[
								'common_message_forbidden'],
							duration: 5000,
							icon: 'none'
						})
					}
          // 请求资源不存在
					if (status === 404) {
						return uni.showToast({
							title: i18nMessageJsons[message] || i18nMessageJsons[
								'common_message_notFound'],
							duration: 5000,
							icon: 'none'
						})
					}
          // 请求数据异常
					if (status === 422) {
						return uni.showToast({
							title: i18nMessageJsons[message] || i18nMessageJsons[
								'common_message_unprocessableEntity'],
							duration: 5000,
							icon: 'none'
						})
					}
          // 服务访问异常
					if (status === 503) {
						return uni.showToast({
							title: i18nMessageJsons[message] || i18nMessageJsons[
								'common_message_serviceUnavailable'],
							duration: 5000,
							icon: 'none'
						})
					}
          // 服务器内部异常
					if (status === 500) {
						return uni.showToast({
							title: i18nMessageJsons[message] || i18nMessageJsons[
								'common_message_internalServerError'],
							duration: 5000,
							icon: 'none'
						})
					}
          // 其他异常
					return uni.showToast({
						title: i18nMessageJsons[message],
						duration: 5000,
						icon: 'none'
					})
				}
				resolve(res) //成功,将数据返回
			},
			fail: (err) => { //失败操作
				uni.hideLoading();
				return uni.showToast({
					title: errorCode['fail'],
					duration: 5000,
					icon: 'none'
				})
				reject(err)
			}
		});

Uniapp 接口请求参数说明 ​
请求方式参数请求头后台接收参数示例
GETparams : json参数'Content-Type': 'application
/x-www-form-urlencoded'
普通类型 Integer、String ...String id、Integer sort
GET/' + id'Content-Type': 'application
/x-www-form-urlencoded'
@PathVariable("id")
String Id
@PathVariable("userId")
String userId
POSTdata : 对象'Content-Type':
'application/json'
@RequestBody Objuec obj@RequestBody Goods
goods
POSTparams : json参数'Content-Type': 'application
/x-www-form-urlencoded'
普通类型 Integer、String ...String id、Integer sort
PUTdata : 对象'Content-Type':
'application/json'
@RequestBody Objuec obj@RequestBody Goods
goods
PUTparams : json参数'Content-Type': 'application
/x-www-form-urlencoded'
普通类型 Integer、String ...String id、Integer sort
DELETEparams : json参数'Content-Type': 'application
/x-www-form-urlencoded'
普通类型 Integer、String ...String id、Integer sort
DELETE/' + id'Content-Type': 'application
/x-www-form-urlencoded'
@PathVariable("id")
String Id
@PathVariable("userId")
String userId

各模块业务接口 ​

后端接口按使用端组织,平台管理端、商家端、商城端各有独立前缀,服务之间还有一层内部调用接口(仅供各服务模块相互调用、不对外开放。两种部署模式下接口路径与访问端口一致,前端不区分模式。

各模块的列表、新增、编辑、删除遵循统一的增删改查约定,下文不再逐一罗列;每个模块先说明这块接口做什么,再把有业务动作的关键接口列表呈现。

一、登录与注册 ​

会员支持手机号验证码、邮箱验证码、邮箱密码三种方式登录,并可接入第三方社交登录。邮箱注册先获取验证码(有效期五分钟、一分钟内不可重发),验证通过后以邮箱作为登录账号;带推广参数进入的注册会自动绑定分销上级。邮箱密码登录时按登录名是否为邮箱格式决定校验方式。商家注册流程相似,额外校验商家智能参数字段。忘记密码通过邮箱找回,系统发送带时效的重置链接。

方法路径说明
POST/shop/register/email_code发送邮箱注册验证码
POST/shop/register/email_submit邮箱验证码注册,邮箱作登录账号
POST/oauth/token登录发放令牌,登录名含 @ 按邮箱校验
POST/shop/password/forgot邮箱找回密码,发送重置链接

二、会员与账户 ​

平台管理端维护会员资料、会员等级、会员标签、会员智能参数,并可对会员积分与预存款做人工调整。会员端维护个人资料与收货地址、收藏商品与店铺、查看积分与预存款明细、开通付费会员。日常的资料与收藏走通用增删改查,关键接口是资金与开通类动作。

方法路径说明
POST/admin/member_deposit/adjust人工调整会员余额,写预存款流水
POST/member/paid_member/buy开通/续费付费会员,按套餐扣余额、记有效期
GET/member/member_center/info会员中心:等级、生效中的付费会员、权益

三、会员提现 ​

会员发起预存款提现后对应金额冻结,平台审核。审核通过时扣减并解冻余额,PayPal 渠道随后自动打款、以批次号保证不重复打款,打款结果由回调回写;回调丢失时可在管理端手动查证补齐。手动渠道由财务线下打款后确认到账。审核拒绝或打款失败时解冻退回余额并记录原因。商家提现、分销提现共用同一套打款机制。

方法路径说明
POST/shop/member_withdrawal/save会员申请提现,冻结对应金额
GET/admin/member_withdrawal/review平台审核,通过则扣减解冻并发起打款
GET/admin/member_withdrawal/mark_paid手动渠道确认打款到账
GET/admin/member_withdrawal/query_payout主动查证 PayPal 打款状态

四、商家与店铺 ​

商家账号注册与开店申请是两步:注册创建商家账号,开店申请提交店铺资料后由平台审核。审核通过按店铺等级决定直接开通还是待缴费,拒绝需填原因,被拒后可重新提交。经营范围调整走经营分类申请,另有店铺签约与工商变更两条独立审核流程。商家端维护店铺设置、配送与地区运费、售后设置,查看余额并可提现或充值。

方法路径说明
POST/merchant/store/register商家提交开店申请
POST/admin/store/review平台审核开店申请,通过或驳回
GET/admin/management_classification/review审核经营分类申请
PUT/admin/store_sign/approve、/reject店铺签约审核
PUT/admin/business_change/approve、/reject工商变更审核

五、商品 ​

平台管理端管理全平台商品,可批量上架下架(上架前校验分类在店铺经营范围内),并维护分类、品牌、标签、参数、属性、规格等基础数据。商家端发布与维护自己的商品,按分类带出参数、属性、规格模板,配置各规格的价格与库存。商城端提供商品详情、搜索、分类、推荐、对比等浏览接口。库存以出入库方式管理,销售扣减发生在发货时;缺货商品可由会员登记到货通知,到货后商家群发。

方法路径说明
POST/admin/goods/shelves、/shelf批量上架、下架商品
POST/biz/stock/stock_in、/stock_out商家入库、出库并记录流水
POST/biz/goods_notify/send到货后向登记会员群发通知

六、订单与售后 ​

订单从下单、支付、发货、收货到完成逐步流转。结算时汇总商品金额、运费、活动与优惠券折扣、积分抵现得出应付金额;平台开启积分抵现时会员可在结算页使用积分抵扣,下单即扣分、取消或退款时退回。支付支持在线支付、余额支付与货到付款,在线支付结果由渠道异步回调确认。

发货是商家的关键动作:选择快递、填运单号、逐项填发货数量,系统校验后扣库存并置为已发货,物流轨迹对接快递查询。买家确认收货后,订单完成时集中发放赚分、赠券、累计消费额、结算分销佣金与商户货款。售后分退款、退货、换货、维修:退款审核通过即退款到会员余额,退货需买家寄回、商家收货后完成并回补库存,退款同时冲回该订单已发的分销佣金。

方法路径说明
GET/member/order/calculate结算试算,含积分抵现折减
POST/member/order/create提交订单,写抵扣并扣分
POST/biz/order/shipping商家发货,校验后扣库存置已发货
POST/member/order/receive买家确认收货
POST/biz/order/complete订单完成,集中结算赚分与佣金货款
POST/member/refunds/refunds、/returns、/replace、/repair买家申请退款/退货/换货/维修
POST/biz/aftersales/review、/complete商家审核、完成售后

七、营销与优惠券 ​

平台内置秒杀、团购、买赠、满减、免运费几种营销方式,管理端可开关每种方式并设置服务费,查看和删除各店铺的活动。商家购买营销方式后在有效期内创建活动,配置活动商品、价格、时间、参与会员等级;商城端浏览进行中的活动与活动商品价格。优惠券由商家创建券模板并生成券码,可设为直接领取或积分兑换,会员领取或兑换后下单抵扣。

方法路径说明
POST/biz/seckill_marketing/save、/update商家创建、修改活动(秒杀等各类同构)
GET/shop/seckill_marketing/list商城端浏览进行中的活动商品
GET/biz/coupon/generate生成优惠券码
GET/shop/coupon_code/get_coupon会员领券
POST/shop/coupon_code/exchange积分兑换优惠券

八、积分 ​

平台以积分设置统一管理下单赚分比例、积分抵现比例与开关、每日抽奖上限等,下单结算与抽奖时实时读取。积分抽奖是大转盘活动:管理端配置活动与奖品池,会员消耗积分抽奖,命中后按奖品类型自动发放——积分即时到账、优惠券自动发放、实物生成待发货记录,抽空时退回积分。实物奖品由运营填快递发出,积分商城展示可用积分兑换的商品。

方法路径说明
GET/member/point_lottery/current当前抽奖活动与本人可抽次数
POST/member/point_lottery/draw抽奖:扣分、按概率发奖、抽空退分
POST/admin/point_lottery_shipment/ship实物奖品填快递发货

九、分销 ​

管理端维护分销员、设置分销商品佣金比例、配置分销全局参数、发布分销通知,并审核分销提现。会员通过推广链接注册即建立分销上下级关系,订单完成后按比例结算直接与间接佣金,退款时冲回。分销员在会员端查看佣金明细并发起提现,对违规分销员可封禁。

方法路径说明
POST/admin/distribution_goods/batchSave批量设置分销商品佣金率
GET/admin/distribution_withdrawal/review审核分销提现
POST/shop/distribution_withdrawal/save分销员申请提现

十、直播 ​

商家申请直播权限,提交资质并完成手机验证后由平台审核开通。开通后创建直播间,设置标题、封面、时间与关联商品,系统生成推流与观众拉流地址。直播状态在未开始、直播中、已结束之间流转,观众在直播间可直接购买关联商品。

方法路径说明
PUT/admin/live_permission/approve、/reject审核商家直播权限申请
POST/admin/live_room/save、/goods/save创建直播间、挂接直播商品

十一、内容与装修 ​

平台公告支持分类、多语言、定时发布、置顶与按人群定向投放。发布时按目标人群解析出收件人写入会员站内信,会员按自己的语言查看、打开即标记已读,管理端可看已读统计。客服自动回复由商家按店铺维护关键词与回复内容,买家咨询命中时自动应答。媒体库按平台与店铺两个作用域管理素材。页面装修以可视化方式编排商城页面,每页按终端与语言维护草稿,发布后写入版本快照可回滚,也可套用模板包批量生成;配套的弹窗、轮播、底部导航按终端与时间窗投放,整站配色由激活的主题决定。

方法路径说明
PUT/admin/platform_announcement/publish发布公告,按人群写入收件箱
GET/admin/platform_announcement/read_stats公告已读统计
PUT/admin/decoration_page/publish、/rollback装修页发布、版本回滚
PUT/admin/decoration_theme/set_active激活主题

十二、多语言与多币种 ​

业务文案由后端按语言提供、前端按需拉取。管理端维护支持的语种、货币、汇率与国家码。货币管理支持基准币治理与币种间换算;汇率采用追加方式维护,每次调价新增一条并即时生效,保留历史可追溯。会员端可选择展示语言与币种,商品价格按当前汇率折算展示,下单时锁定汇率快照。

方法路径说明
POST/admin/exchange_rate/save追加一条汇率,即时生效
PUT/admin/currency/set_base设置基准币,重算汇率表
GET/shop/currency/list商城端取启用币种与当前汇率

十三、数据分析与财务 ​

数据分析基于前端埋点与每日聚合,提供流量、访客、页面、商品、会员留存等报表,按日期区间查询,缺数时可手动重算。财务管理提供营收总览、财务明细、店铺结算与对账:营收总览按日汇总订单额、退款额与净收入;店铺结算按周期生成结算单与逐单明细,货款在订单完成时已实时入账,确认结算只做核销归档;财务对账按周期核对收入与退款流水。

方法路径说明
POST/admin/analytics/rebuild手动重算指定日期的分析数据
GET/admin/analytics/member/retention会员留存报表
PUT/admin/store_settlement/confirm确认店铺结算

十四、第三方回调 ​

支付与打款依赖第三方异步回调:支付回调验签后完成订单支付,打款回调触发提现单状态回写。回调路径微服务模式在网关放行、单体模式由应用直接暴露,回调内均以主动查证渠道真实状态为准,不轻信回调内容。

方法路径说明
POST/webhook/stripeStripe 支付回调,验签后完成支付
POST/webhook/paypal_payoutPayPal 打款回调,回写提现单状态

版权许可