Mini Program Expert Skill

This skill guides you through extending the RuoYi-Vue backend to support WeChat Mini Program (小程序) authentication and developing the frontend. It supports both Native Development (using WeChat Developer Tools directly) and UniApp (Cross-platform).

1. Backend Integration (Spring Boot) – Common

1.1 Add Dependencies

Add the weixin-java-miniapp dependency to your ruoyi-common/pom.xml (or ruoyi-framework):

<dependency>
    <groupId>com.github.binarywang</groupId>
    <artifactId>weixin-java-miniapp</artifactId>
    <version>4.5.0</version>
</dependency>

1.2 Configuration

Add WeChat configuration to ruoyi-admin/src/main/resources/application.yml:

wx:
  miniapp:
    appid: your_app_id
    secret: your_app_secret
    token: your_token
    aesKey: your_aes_key
    msgDataFormat: JSON

Create a Config class WxMaConfiguration.java in ruoyi-framework:

@Configuration
public class WxMaConfiguration {
    @Value("${wx.miniapp.appid}")
    private String appid;
    // ... other fields

    @Bean
    public WxMaService wxMaService() {
        WxMaDefaultConfigImpl config = new WxMaDefaultConfigImpl();
        config.setAppid(appid);
        // ... set other fields
        WxMaService service = new WxMaServiceImpl();
        service.setWxMaConfig(config);
        return service;
    }
}

1.3 Implement Login Logic

Extend SysLoginService or create WxLoginService to handle code-to-token exchange.

Workflow:

1. Frontend calls wx.login() to get code.
2. Frontend sends code to backend /login/wx.
3. Backend uses WxMaService.getUserService().getSessionInfo(code) to get openid.
4. Backend looks up SysUser by openid (you need to add an openid column to sys_user table).
5. If user exists, generate JWT token using tokenService.createToken(loginUser).
6. If user does not exist, either auto-register or return a specific code to prompt binding.

2. Frontend Development Options

Choose your preferred development path.

Option A: Native Development (WeChat Developer Tools)

Best for: Maximum performance, direct access to latest WeChat features, using WeChat Developer Tools only.

2.A.1 Project Setup

1. Open WeChat Developer Tools.
2. Create a new project pointing to a local directory.
3. Select “Weixin” (Native) template.

2.A.2 Encapsulate Request (utils/request.js)

Create a utility to handle JWT tokens automatically.

// utils/request.js
const baseUrl = 'http://localhost:8080';

const request = (options) => {
  return new Promise((resolve, reject) => {
    wx.request({
      url: baseUrl + options.url,
      method: options.method || 'GET',
      data: options.data || {},
      header: {
        'Authorization': 'Bearer ' + wx.getStorageSync('token') // Attach Token
      },
      success: (res) => {
        if (res.statusCode === 401) {
            // Token expired
            wx.reLaunch({ url: '/pages/login/login' });
        } else if (res.data.code === 200) {
            resolve(res.data);
        } else {
            wx.showToast({ title: res.data.msg, icon: 'none' });
            reject(res.data);
        }
      },
      fail: reject
    });
  });
};

module.exports = request;

2.A.3 Login Page (pages/login/login.js)

const request = require('../../utils/request.js');

Page({
  handleLogin() {
    wx.login({
      success: (res) => {
        if (res.code) {
          request({
            url: '/login/wx',
            method: 'POST',
            data: { code: res.code }
          }).then(data => {
            wx.setStorageSync('token', data.token);
            wx.switchTab({ url: '/pages/index/index' });
          });
        }
      }
    });
  }
})

Option B: UniApp (HBuilderX)

Best for: Cross-platform (WeChat, Alipay, H5, App), Vue.js syntax.

2.B.1 Project Structure

Use HBuilderX to create a uni-app project.

2.B.2 Encapsulate Request

Use uni.request and uni.getStorageSync which are cross-platform wrappers.

/* request.js logic is similar to Native but uses `uni.` namespace */

2.B.3 Running in WeChat Developer Tools

1. In HBuilderX, go to Run -> Run to MiniProgram Simulator -> Weixin DevTools.
2. This will compile your Vue code to WXML/WXSS and auto-open the WeChat Developer Tools for you.

3. Best Practices Rules

• Stateless: Always use JWT. Do not rely on Cookies/Session in Mini Programs.
• Security: Never expose AppSecret in the frontend code.
• Components:
  • Native: Use libraries like Vant Weapp.
  • UniApp: Use uView UI or ThorUI.