接口设计说明书
Java后台接口
接口返回参数
java
// 返回标记:成功=0,失败=1
private int status;
// 返回信息
private String message;
// 数据
private T data;接口返回方法
| 方法 | 返回http状态 | 方法返回参数 | 描述 |
|---|---|---|---|
| ok | 200 | 数据、状态及异常编码 | 正常 |
| failed | 400 | 数据、状态及异常编码 | 请求发生错误 |
| unauthorized | 401 | 数据、状态及异常编码 | 认证异常 |
| forbidden | 403 | 数据、状态及异常编码 | 没有权限 |
| notFound | 404 | 数据、状态及异常编码 | 请求资源不存在 |
| unprocessableEntity | 422 | 数据、状态及异常编码 | 请求数据异常 |
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请求参数说明
| 请求方式 | 参数 | 后台接收参数 | 示例 |
|---|---|---|---|
| GET | params : json参数 | 普通类型 Integer、String ... | String id、Integer sort |
| GET | /' + id | @PathVariable("id") String Id | @PathVariable("userId") String userId |
| POST | data : 对象 | @RequestBody Objuec obj | @RequestBody Goods |
| goods | |||
| POST | params : json参数 | 普通类型 Integer、String ... | String id、Integer sort |
| PUT | data : 对象 | @RequestBody Objuec obj | @RequestBody Goods |
| goods | |||
| PUT | params : json参数 | 普通类型 Integer、String ... | String id、Integer sort |
| DELETE | params : 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 接口请求参数说明
| 请求方式 | 参数 | 请求头 | 后台接收参数 | 示例 |
|---|---|---|---|---|
| GET | params : 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 |
| POST | data : 对象 | 'Content-Type': 'application/json' | @RequestBody Objuec obj | @RequestBody Goods goods |
| POST | params : json参数 | 'Content-Type': 'application /x-www-form-urlencoded' | 普通类型 Integer、String ... | String id、Integer sort |
| PUT | data : 对象 | 'Content-Type': 'application/json' | @RequestBody Objuec obj | @RequestBody Goods goods |
| PUT | params : json参数 | 'Content-Type': 'application /x-www-form-urlencoded' | 普通类型 Integer、String ... | String id、Integer sort |
| DELETE | params : 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/stripe | Stripe 支付回调,验签后完成支付 |
| POST | /webhook/paypal_payout | PayPal 打款回调,回写提现单状态 |
BizSpring