Appearance

微信小程序开发文档 ​

1. 概述 ​

微信小程序模块是系统中负责微信小程序集成和管理的核心功能，支持微信小程序的配置管理、域名设置、隐私协议设置、订阅消息管理、版本管理等功能，为系统提供与微信小程序的深度集成能力。

2. 功能模块 ​

2.1 微信小程序配置管理 ​

2.1.1 基本配置 ​

  • 小程序名称
  • 原始ID
  • AppID
  • AppSecret
  • 小程序二维码
  • Token
  • EncodingAESKey
  • 加解密模式
  • 上传私钥

2.1.2 域名设置 ​

  • request域名
  • wsrequest域名
  • upload域名
  • download域名
  • udp域名
  • tcp域名

2.1.3 隐私协议设置 ​

  • 设置列表
  • 所有者设置
  • SDK隐私信息列表

2.2 订阅消息管理 ​

2.2.1 模板列表 ​

  • 查看可用的订阅消息模板
  • 设置模板参数

2.2.2 模板配置 ​

  • 配置模板ID
  • 设置模板变量

2.3 小程序版本管理 ​

2.3.1 版本列表 ​

  • 查看小程序版本历史
  • 管理版本状态

2.3.2 版本上传 ​

  • 上传小程序代码
  • 获取预览码
  • 查看上传日志

2.4 小程序发货信息管理 ​

  • 查询小程序是否已开通发货信息管理服务

2.5 消息记录 ​

2.5.1 消息记录列表 ​

  • 查看微信小程序消息发送记录
  • 按条件筛选记录

2.5.2 消息详情 ​

  • 查看消息发送状态
  • 查看消息内容

3. 代码实现 ​

3.1 路由配置 ​

php
// 微信小程序模块路由配置
Route::group('weapp', function() {
    /***************************************************** 微信配置 ****************************************************/
    Route::get('config', 'weapp.Config/get');
    // 设置微信配置
    Route::put('config', 'weapp.Config/set');
    // 设置微信域名
    Route::put('domain', 'weapp.Config/setDomain');
    // 设置微信隐私协议
    Route::put('privacysetting', 'weapp.Config/setPrivacySetting');
    // 获取微信隐私协议
    Route::get('privacysetting', 'weapp.Config/getPrivacySetting');

    /***************************************************** 订阅消息 ****************************************************/
    Route::get('template', 'weapp.Template/lists');
    // 设置订阅消息
    Route::put('template', 'weapp.Template/set');

    /***************************************************** 小程序版本管理 ****************************************************/
    // 添加版本
    Route::post('version', 'weapp.Version/add');
    // 版本列表
    Route::get('version', 'weapp.Version/lists');
    // 获取预览码
    Route::get('preview', 'weapp.Version/preview');
    // 获取小程序上传日志
    Route::get('upload/:key', 'weapp.Version/uploadLog');


    /***************************************************** 小程序发货信息管理服务 ****************************************************/

    // 查询小程序是否已开通发货信息管理服务
    Route::get('delivery/getIsTradeManaged', 'weapp.Delivery/getIsTradeManaged');

    /***************************************************** 消息记录 ****************************************************/
    // 消息记录列表
    Route::get('log', 'weapp.WeappLog/lists');
    // 消息记录详情
    Route::get('log/:id', 'weapp.WeappLog/info');

});

3.2 微信小程序配置控制器 ​

php
<?php

namespace app\adminapi\controller\weapp;

use app\service\admin\weapp\WeappConfigService;
use core\base\BaseAdminController;
use think\Response;

/**
 * 微信小程序配置
 */
class Config extends BaseAdminController
{
    /**
     * 获取微信小程序配置信息
     * @description 获取微信小程序配置信息
     * @return Response
     */
    public function get()
    {
        return success((new WeappConfigService())->getWeappConfig());
    }

    /**
     * 设置微信小程序配置信息
     * @description 设置微信小程序配置信息
     * @return Response
     */
    public function set()
    {
        $data = $this->request->params([
            ['weapp_name', ''],
            ['weapp_original', ''],
            ['app_id', ''],
            ['app_secret', ''],
            ['token', ''],
            ['encoding_aes_key', ''],
            ['qr_code', ''],
            ['encryption_type', ''],
            ['upload_private_key', '']
        ]);
        $this->validate($data, 'app\validate\channel\Weapp.set');
        (new WeappConfigService())->setWeappConfig($data);
        return success('SET_SUCCESS');
    }

    /**
     * 设置微信小程序域名
     * @description 设置微信小程序域名
     * @return Response
     */
    public function setDomain() {
        $data = $this->request->params([
            ['requestdomain', ''],
            ['wsrequestdomain', ''],
            ['uploaddomain', ''],
            ['downloaddomain', ''],
            ['udpdomain', ''],
            ['tcpdomain', '']
        ]);
        (new WeappConfigService())->setDomain($data);
        return success('SET_SUCCESS');
    }

    /**
     * 获取微信小程序隐私协议
     * @description 获取微信小程序隐私协议
     * @return Response
     */
    public function getPrivacySetting() {
        return success((new WeappConfigService())->getPrivacySetting());
    }

    /**
     * 设置微信小程序隐私协议
     * @description 设置微信小程序隐私协议
     * @return Response
     */
    public function setPrivacySetting() {
        $data = $this->request->params([
            ['setting_list', []],
            ['owner_setting', []],
            ['sdk_privacy_info_list', []]
        ]);
        (new WeappConfigService())->setPrivacySetting($data);
        return success('SET_SUCCESS');
    }
}

3.3 微信小程序配置服务 ​

php
<?php

namespace app\service\admin\weapp;

use app\dict\common\CommonDict;
use app\model\sys\SysConfig;
use app\service\core\weapp\CoreWeappConfigService;
use core\base\BaseAdminService;
use think\Model;

/**
 * 微信小程序设置
 */
class WeappConfigService extends BaseAdminService
{
    /**
     * 获取配置信息
     * @return array|null
     */
    public function getWeappConfig()
    {
        $config_info = (new CoreWeappConfigService())->getWeappConfig();
        foreach ($config_info as $k => $v) {
            if ($v !== '' && in_array($k, ['app_secret', 'encoding_aes_key'])) {
                $config_info[$k] = CommonDict::ENCRYPT_STR;
            }
        }
        return array_merge($config_info, $this->getWeappStaticInfo());

    }

    /**
     * 设置配置
     * @param array $data
     * @return SysConfig|bool|Model
     */
    public function setWeappConfig(array $data){
        $config = (new CoreWeappConfigService())->getWeappConfig();
        foreach ($data as $k => $v) {
            if ($v == CommonDict::ENCRYPT_STR) {
                $data[$k] = $config[$k];
            }
        }
        return (new CoreWeappConfigService())->setWeappConfig($data);
    }

    /**
     *查询微信小程序需要的静态信息
     * @return array
     */
    public function getWeappStaticInfo(){
        $domain = request()->domain();
        $domain = str_replace('http://', 'https://', $domain);
        return [
            'serve_url' => (string)url('/api/weapp/serve', [],'',true),
            'request_url' => $domain,
            'socket_url'   => "wss://".request()->host(),
            'upload_url'  => $domain,
            'download_url'   => $domain,
            'upload_ip' => gethostbyname('oss.niucloud.com')
        ];
    }
}

3.4 核心微信小程序配置服务 ​

php
<?php

namespace app\service\core\weapp;

use app\dict\sys\ConfigKeyDict;
use app\model\sys\SysConfig;
use app\service\core\sys\CoreConfigService;
use core\base\BaseCoreService;
use think\Model;

/**
 * 微信小程序配置
 */
class  CoreWeappConfigService extends BaseCoreService
{
    /**
     * 获取微信小程序设置
     * @return array
     */
    public function getWeappConfig()
    {
        $info = ( new CoreConfigService() )->getConfig(ConfigKeyDict::WEAPP)[ 'value' ] ?? [];
        return [
            'weapp_name' => $info[ 'weapp_name' ] ?? '',//小程序名称
            'weapp_original' => $info[ 'weapp_original' ] ?? '',//原始ID
            'app_id' => $info[ 'app_id' ] ?? '',//AppID
            'app_secret' => $info[ 'app_secret' ] ?? '',//AppSecret
            'qr_code' => $info[ 'qr_code' ] ?? '',//小程序二维码
            'token' => $info[ 'token' ] ?? '',
            'encoding_aes_key' => $info[ 'encoding_aes_key' ] ?? '',
            'encryption_type' => $info[ 'encryption_type' ] ?? 'not_encrypt',//加解密模式   not_encrypt 明文   compatible 兼容  safe 安全
            'upload_private_key' => $info[ 'upload_private_key' ] ?? '',
            'is_authorization' => $info[ 'is_authorization' ] ?? 0
        ];
    }

    /**
     * 微信小程序配置
     * @param array $data
     * @return SysConfig|bool|Model
     */
    public function setWeappConfig(array $data)
    {
        $old = $this->getWeappConfig();
        $config = [
            'weapp_name' => $data[ 'weapp_name' ] ?? '',//小程序名称
            'weapp_original' => $data[ 'weapp_original' ] ?? '',//原始ID
            'app_id' => $data[ 'app_id' ] ?? '',//AppID
            'app_secret' => $data[ 'app_secret' ] ?? '',//AppSecret
            'qr_code' => $data[ 'qr_code' ] ?? '',//小程序二维码
            'token' => $data[ 'token' ] ?? '',
            'encoding_aes_key' => $data[ 'encoding_aes_key' ] ?? '',
            'encryption_type' => $data[ 'encryption_type' ] ?? 'not_encrypt',//加解密模式   not_encrypt 明文   compatible 兼容  safe 安全
            'upload_private_key' => $data[ 'upload_private_key' ] ?? '',
            'is_authorization' => $data[ 'is_authorization' ] ?? $old[ 'is_authorization' ]
        ];
        return ( new CoreConfigService() )->setConfig(ConfigKeyDict::WEAPP, $config);
    }

    /**
     * 获取小程序授权信息
     * @return mixed
     */
    public function getWeappAuthorizationInfo()
    {
        return ( new CoreConfigService() )->getConfigValue(ConfigKeyDict::WEAPP_AUTHORIZATION_INFO);
    }

    /**
     * 设置小程序授权信息
     * @param array $config
     * @return SysConfig|bool|Model
     */
    public function setWeappAuthorizationInfo(array $config)
    {
        return ( new CoreConfigService() )->setConfig(ConfigKeyDict::WEAPP_AUTHORIZATION_INFO, $config);
    }

    /**
     * 清除小程序授权信息
     * @param array $config
     * @return SysConfig|bool|Model
     */
    public function clearWeappAuthorizationInfo()
    {
        return ( new CoreConfigService() )->clearConfig(ConfigKeyDict::WEAPP_AUTHORIZATION_INFO);
    }
}

4. 微信小程序配置流程 ​

4.1 基本配置流程 ​

  1. 登录微信公众平台（https://mp.weixin.qq.com/）
  2. 进入开发 -> 开发设置
  3. 获取AppID和AppSecret
  4. 设置服务器地址（URL）：填写系统提供的服务器地址
  5. 设置Token：与系统中配置的Token保持一致
  6. 设置EncodingAESKey：与系统中配置的EncodingAESKey保持一致
  7. 选择加解密模式：与系统中配置的加解密模式保持一致
  8. 点击提交，完成配置

4.2 域名设置流程 ​

  1. 登录系统后台
  2. 进入微信小程序 -> 配置管理
  3. 填写request域名、wsrequest域名、upload域名、download域名等
  4. 点击保存，完成域名设置
  5. 登录微信公众平台，在开发设置中确认域名配置

4.3 隐私协议设置流程 ​

  1. 登录系统后台
  2. 进入微信小程序 -> 隐私协议设置
  3. 配置设置列表、所有者设置和SDK隐私信息列表
  4. 点击保存，完成隐私协议设置
  5. 登录微信公众平台，在设置 -> 基本设置 -> 服务内容声明中确认隐私协议配置

4.4 订阅消息配置流程 ​

  1. 登录微信公众平台
  2. 进入功能 -> 订阅消息
  3. 选择需要的订阅消息模板
  4. 获取模板ID
  5. 登录系统后台，进入微信小程序 -> 订阅消息管理
  6. 填写模板ID和相关参数
  7. 点击保存，完成订阅消息配置

4.5 版本管理流程 ​

  1. 登录系统后台
  2. 进入微信小程序 -> 版本管理
  3. 上传小程序代码
  4. 获取预览码进行测试
  5. 提交审核
  6. 发布版本

5. 数据模型 ​

5.1 微信小程序通知模型 ​

  • 表名：weapp_notice
  • 主要字段：
    • id：通知ID
    • key：通知键名
    • is_weapp：是否启用小程序通知
    • template_id：模板ID
    • data：通知数据
    • create_time：创建时间
    • update_time：更新时间

5.2 微信小程序消息记录模型 ​

  • 表名：weapp_log
  • 主要字段：
    • id：记录ID
    • template_id：模板ID
    • openid：用户OpenID
    • data：消息数据
    • status：发送状态
    • error_msg：错误信息
    • create_time：发送时间

5.3 微信小程序版本模型 ​

  • 表名：weapp_version
  • 主要字段：
    • id：版本ID
    • version：版本号
    • description：版本描述
    • status：版本状态
    • create_time：创建时间
    • update_time：更新时间

6. 开发注意事项 ​

6.1 安全考虑 ​

  • AppSecret和EncodingAESKey等敏感信息应加密存储
  • 微信小程序的Token应定期更新
  • 验证微信消息的真实性，防止伪造消息
  • 小程序代码应进行安全检测，防止安全漏洞

6.2 性能优化 ​

  • 微信接口调用应设置合理的缓存策略
  • 消息处理应采用异步处理，避免阻塞主流程
  • 小程序代码应进行压缩，减少包大小
  • 图片和资源应进行优化，提高加载速度

6.3 错误处理 ​

  • 微信接口调用失败时应进行重试机制
  • 记录详细的错误信息，便于排查问题
  • 对用户友好的错误提示
  • 小程序应具备离线能力，在网络不稳定时仍能正常运行

6.4 最佳实践 ​

  • 合理设计小程序的页面结构和导航
  • 优化用户体验，减少用户操作步骤
  • 定期更新小程序版本，修复bug和添加新功能
  • 关注微信小程序平台的规则变化，及时调整策略
  • 利用微信小程序的特性，如缓存、本地存储等，提高用户体验

7. 常见问题 ​

7.1 小程序登录失败 ​

  • 检查AppID和AppSecret是否正确
  • 确认服务器地址是否配置正确
  • 检查网络连接是否正常
  • 查看小程序日志，排查错误原因

7.2 域名配置失败 ​

  • 检查域名是否已备案
  • 确认域名是否符合微信小程序的域名要求
  • 检查SSL证书是否有效
  • 查看微信公众平台的错误提示

7.3 订阅消息发送失败 ​

  • 检查模板ID是否正确
  • 确认用户是否已授权订阅该消息
  • 检查消息数据格式是否符合要求
  • 查看消息记录，排查发送状态

7.4 小程序上传失败 ​

  • 检查小程序代码是否符合微信小程序的代码规范
  • 确认上传私钥是否正确
  • 检查网络连接是否正常
  • 查看上传日志，排查错误原因

8. 总结 ​

微信小程序模块是系统中重要的移动应用入口，通过本文档的指导，开发人员可以了解微信小程序管理的核心功能和实现逻辑，从而更好地集成和扩展微信小程序功能。系统支持微信小程序的配置管理、域名设置、隐私协议设置、订阅消息管理、版本管理等功能，为企业提供了与用户进行移动端互动的有效渠道。