微应用后端开发

服务端接口

通用服务端接口封装于公共模块的MiniAppCommonService服务类中，通过注入该服务类获取服务类的实例，使用示例：

@Resource
private MiniAppCommonService miniAppCommonService;

@Resource
private MiniAppPayService miniAppPayService;
    
ApplicationVo application = miniAppCommonService.getApplication();
// ...

在使用服务端接口之前需要先正确配置微应用的appKey和appSecret，该配置主要用于微应用后端向 Mos 服务端发起请求时，对请求参数进行签名，具体的签名方式开发者无需关心，公共服务已经封装好了，开发者注入相应服务后，直接调用具体方法名即可。

接口BaseURL

• 测试环境：https://mos-test.mos.me
• 生产环境：https://mos.mos.me

接口签名

如果直接用 HTTP 的方式调用，请求体 Body 中必须增加以下字段：

• appKey：微应用 App Key
• sign：签名

签名生成规则：将包含appKey在内的所有参数按升序排序然后转换为QueryString的格式（例如 key1=value1&key2=value2...），再在末尾拼接上 secret=appSecret，最后对这个字符串进行 MD5 即得到签名，Java 示例代码如下：

import org.springframework.util.DigestUtils;

/**
 * 获取签名
 *
 * @param request 请求，这里用 Object 作为示例，实际应该替换为请求体对应的类型或请求基类
 * @return 签名
 */
public String getSign(Object request) {
    // 将请求转换为Key有序的 TreeMap 默认升序，"appKey" 也需要包含在内
    Map<String, String> requestSortedMap = JSON.parseObject(JSON.toJSONString(request), new TypeReference<TreeMap<String, String>>() {
    });
    requestSortedMap.put("appKey", "<your_app_key>");

    // 请求转换为 QueryString 格式，如 key1=value1&key2=value2...
    StringBuilder qsBuilder = new StringBuilder();
    for (Map.Entry<String, String> entry : requestSortedMap.entrySet()) {
        // "sign" 或空值不参与签名
        if ("sign".equals(entry.getKey()) || entry.getValue() == null || entry.getValue().isEmpty()) {
            continue;
        }
        qsBuilder.append(entry.getKey()).append("=").append(entry.getValue().trim()).append("&");
    }
    // 在末尾拼接上 "secret=your_app_secret"
    qsBuilder.append("secret=").append("<your_app_secret>");

    // MD5处理
    return DigestUtils.md5DigestAsHex(qsBuilder.toString().getBytes(StandardCharsets.UTF_8));
}

登录鉴权

获取应用信息

API：MiniAppCommonService.getApplication() HTTP：POST /open-apis/application/v1/getApplication

获取微应用应用信息

参数 无

响应

属性	类型	说明
appName	String	应用名称
appKey	String	应用key
appSecret	String	应用密匙
description	String	应用描述
status	Boolean	应用状态
notifyUrl	String	应用回调地址

通用登录

API：MiniAppCommonService.miniAppLogin(String code)

公共模块提供的通用登录接口，通过在小程端获取的 code 和 JWT 生成身份令牌。微应用模块新建后会自带一个默认的登录拦截器com.testproject.mos.miniapp.xxx.interceptor.LoginInterceptor在这个拦截器中会校验微应用前端传过来的令牌，微应用前端使用 Bearer token 的格式传递，Http Header：

Authorization: Bearer <token>

鉴权通过后，用户可以通过「获取当前用户信息」接口获取登录用户对应的 openid 和语言类型，从而获取微应用自身的用户信息（微应用自身的用户信息需要自己建立用户表，且用户表中必须有一列存储 openid）。

如果通用登录无法满足用户需求，用户可以通过重写登录拦截器，并自行编写登录和获取当前用户信息的接口。

注意：不要修改公共模块的代码

参数

属性	类型	必填	说明
code	String	是	通过微应用 mos.login 获取的 code

响应 TokenVo

属性	类型	说明
token	String	身份令牌

获取当前用户信息

API：MiniAppCommonService.getMiniAppUser()

公共模块提供的通用获取当前登录用户的方法，需要配合通用登录接口和默认的登录拦截器才可生效。

参数 无

响应 MiniAppUserBo

属性	类型	说明
appKey	String	应用key
openid	String	用户唯一标识
languageType	LanguageEnum	语言类型

通过 code 换取Mos会话信息

API：MiniAppCommonService.code2session(String code) HTTP：POST /open-apis/mp/v1/auth/code2session

获取微应用应用信息

参数

属性	类型	必填	说明
code	String	是	通过微应用 mos.login 获取的 code

响应 MosSessionVo

属性	类型	说明
openid	String	用户唯一标识
sessionKey	String	会话Key，暂时没用

支付

在开发支付相关功能之前需要先申请成为Mos商户，获取对应的商户ID（mcId），支付流程需要用到。

创建预支付订单

API：MiniAppPayService.prepay(CreatePrepayOrderAo ao) HTTP：POST /open-apis/mp/v1/pay/prepay

创建预支付订单

参数 CreatePrepayOrderAo

属性	类型	必填	说明
mcId	String	是	商户ID
nonceStr	String	否	随机字符串，需保证系统内唯一
desc	String	否	订单描述
outTradeNo	String	是	商户微应用系统订单号
currency	String	是	货币单位 USD-美元 | KHR-瑞尔
totalAmount	String	是	订单金额
notifyUrl	String	是	回调地址
openid	String	是	用户唯一标识
expireTime	String	否	订单失效时间，时间戳，精确到毫秒

响应 PrepayOrderVo

属性	类型	说明
prepayId	String	预支付订单ID

查询订单

API：MiniAppPayService.orderQuery(OrderQueryAo ao) HTTP：POST /open-apis/mp/v1/pay/orderQuery

查询订单

参数 OrderQueryAo

属性	类型	必填	说明
nonceStr	String	是	随机字符串，需保证系统内唯一
outTradeNo	String	是	商户微应用系统订单号

响应 OrderQueryVo

属性	类型	说明
openid	String	用户唯一标识
prepayId	String	预支付订单ID
outTradeNo	String	商户微应用系统订单号
country	String	国家编码
currency	String	货币单位
totalAmount	String	订单金额
desc	String	商品描述
status	String	订单状态
expireTime	Long	订单失效时间
createTime	Long	创建时间