miaoguo_system_server/MIGRATION_GUIDE.md

迁移指南 - kylx365server → miaoguo_system_server

核心转换规则

1. 模块系统

// 旧: CommonJS
const xxx = require('xxx');
exports.Fn = function* () { ... };

// 新: ESM
import xxx from 'xxx.js';
export async function Fn(ctx) { ... }

2. Koa generator → async/await

// 旧: Koa v1 generator
exports.GetXxx = function* () {
    var param = this.query;
    var result = yield mysql.queryAsync(sql);
    this.body = result;
};

// 新: Koa v2+ async/await
export async function GetXxx(ctx) {
    const param = ctx.query;
    const result = await query(sql, params);
    ctx.body = result;
}

3. 数据库

// 旧: mysql + bluebird, 字符串拼接
var sql = "SELECT * FROM Users WHERE UserID=" + obj.UserID;
return mysql.queryAsync(sql);

// 新: mysql2/promise, 参数化查询
import { query } from '../../util/db.js';
const sql = "SELECT * FROM Users WHERE UserID=?";
return await query(sql, [obj.UserID]);

4. HTTP 请求

// 旧: request-promise
var rp = require('request-promise');
var result = yield rp(url).then(...);

// 新: axios
import axios from 'axios';
const result = await axios.get(url).then(res => res.data);

5. 路由

// 旧: 单文件 routes.js, koa-router v5
var Router = require("koa-router")();
Router.get('/api/Xxx', controller.Xxx);
module.exports = function(app) { app.use(Router.routes()); };

// 新: 模块化 routes.js, @koa/router v13
import Router from '@koa/router';
import * as controller from './controller.js';
const router = new Router();
router.get('/api/Xxx', controller.Xxx);
export default router;

6. ctx 参数映射

this.query           → ctx.query
this.request.body    → ctx.request.body / ctx.request (POST body)
this.params          → ctx.params
this.body            → ctx.body
this.status          → ctx.status
this.throw(status)   → ctx.throw(status)

7. 常用依赖替换

koa-router (v5)       → @koa/router (v13)
koa-multer            → @koa/multer
koa-bodyparser        → koa-bodyparser (已有)
request-promise       → axios
moment                → moment (保留)
lodash                → lodash (保留)
cos-nodejs-sdk-v5     → cos-nodejs-sdk-v5 (保留)
bluebird              → 删除 (mysql2 内置 Promise)

8. 错误处理

// 旧
try { ... } catch(err) { console.log(err); }

// 新
try { ... } catch(err) { console.error('描述:', err); ctx.throw(500, err.message); }

文件放置规则

• Controller: src/api/<module>/<module>Controller.js
• Routes: src/api/<module>/routes.js
• Model: src/model/<module>.js
• 注册路由: 在 src/app.js 中 import 并 use

注意事项

1. 所有 SQL 必须参数化（? 占位符），禁止字符串拼接
2. global.config 改为 import config from '../../config/index.js'
3. BufferMemory 改为 import { globalCache } from '../../util/GlobalCache.js'
4. 保留原有注释和业务逻辑不变
5. WXBizDataCrypt 已存在于 src/util/WXBizDataCrypt.js
6. crypto 工具已存在于 src/util/crypto/index.js
7. stringUtils 已存在于 src/util/stringClass.js