名称: moodle-external-api-development 描述: 为Moodle学习管理系统创建自定义外部web服务API。适用于实施课程管理、用户跟踪、测验操作或自定义插件功能的web服务。涵盖参数验证、数据库操作、错误处理、服务注册和Moodle编码标准。

Moodle外部API开发

此技能指导您如何为Moodle LMS创建自定义外部web服务API，遵循Moodle的外部API框架和编码标准。

何时使用此技能

为Moodle插件创建自定义web服务
为课程管理实施REST/AJAX端点
为测验操作、用户跟踪或报告构建API
向外部应用程序公开Moodle功能
使用Moodle开发移动应用后端

核心架构模式

Moodle外部API遵循严格的三方法模式：

execute_parameters() - 定义输入参数结构
execute() - 包含业务逻辑
execute_returns() - 定义返回结构

逐步实现

步骤1：创建外部API类文件

位置：/local/yourplugin/classes/external/your_api_name.php

<?php
namespace local_yourplugin\external;

defined('MOODLE_INTERNAL') || die();
require_once("$CFG->libdir/externallib.php");

use external_api;
use external_function_parameters;
use external_single_structure;
use external_value;

class your_api_name extends external_api {
    
    // 三个必需的方法将放在这里
    
}

关键点：

类必须扩展external_api
命名空间遵循：local_pluginname\external或mod_modname\external
包含安全检查：defined('MOODLE_INTERNAL') || die();
需要externallib.php用于基类

步骤2：定义输入参数

public static function execute_parameters() {
    return new external_function_parameters([
        'userid' => new external_value(PARAM_INT, '用户ID', VALUE_REQUIRED),
        'courseid' => new external_value(PARAM_INT, '课程ID', VALUE_REQUIRED),
        'options' => new external_single_structure([
            'includedetails' => new external_value(PARAM_BOOL, '包含详细信息', VALUE_DEFAULT, false),
            'limit' => new external_value(PARAM_INT, '结果限制', VALUE_DEFAULT, 10)
        ], '选项', VALUE_OPTIONAL)
    ]);
}

常见参数类型：

PARAM_INT - 整数
PARAM_TEXT - 纯文本（HTML去除）
PARAM_RAW - 原始文本（无清理）
PARAM_BOOL - 布尔值
PARAM_FLOAT - 浮点数
PARAM_ALPHANUMEXT - 字母数字和扩展字符

结构：

external_value - 单个值
external_single_structure - 具有命名字段的对象
external_multiple_structure - 项目数组

值标志：

VALUE_REQUIRED - 必须提供参数
VALUE_OPTIONAL - 参数可选
VALUE_DEFAULT, defaultvalue - 可选且有默认值

步骤3：实现业务逻辑

public static function execute($userid, $courseid, $options = []) {
    global $DB, $USER;

    // 1. 验证参数
    $params = self::validate_parameters(self::execute_parameters(), [
        'userid' => $userid,
        'courseid' => $courseid,
        'options' => $options
    ]);

    // 2. 检查权限/能力
    $context = \context_course::instance($params['courseid']);
    self::validate_context($context);
    require_capability('moodle/course:view', $context);

    // 3. 验证用户访问
    if ($params['userid'] != $USER->id) {
        require_capability('moodle/course:viewhiddenactivities', $context);
    }

    // 4. 数据库操作
    $sql = "SELECT id, name, timecreated
            FROM {your_table}
            WHERE userid = :userid
              AND courseid = :courseid
            LIMIT :limit";
    
    $records = $DB->get_records_sql($sql, [
        'userid' => $params['userid'],
        'courseid' => $params['courseid'],
        'limit' => $params['options']['limit']
    ]);

    // 5. 处理和返回数据
    $results = [];
    foreach ($records as $record) {
        $results[] = [
            'id' => $record->id,
            'name' => $record->name,
            'timestamp' => $record->timecreated
        ];
    }

    return [
        'items' => $results,
        'count' => count($results)
    ];
}

关键步骤：

始终使用validate_parameters()验证参数
使用validate_context()检查上下文
使用require_capability()验证能力
使用参数化查询防止SQL注入
返回结构化数据以匹配返回定义

步骤4：定义返回结构

public static function execute_returns() {
    return new external_single_structure([
        'items' => new external_multiple_structure(
            new external_single_structure([
                'id' => new external_value(PARAM_INT, '项目ID'),
                'name' => new external_value(PARAM_TEXT, '项目名称'),
                'timestamp' => new external_value(PARAM_INT, '创建时间')
            ])
        ),
        'count' => new external_value(PARAM_INT, '总项目数')
    ]);
}

返回结构规则：

必须与execute()返回的内容完全匹配
使用适当的参数类型
用描述记录每个字段
允许嵌套结构

步骤5：注册服务

位置：/local/yourplugin/db/services.php

<?php
defined('MOODLE_INTERNAL') || die();

$functions = [
    'local_yourplugin_your_api_name' => [
        'classname'   => 'local_yourplugin\external\your_api_name',
        'methodname'  => 'execute',
        'classpath'   => 'local/yourplugin/classes/external/your_api_name.php',
        'description' => '此API的简要描述',
        'type'        => 'read',  // 或 'write'
        'ajax'        => true,
        'capabilities'=> 'moodle/course:view', // 多个用逗号分隔
        'services'    => [MOODLE_OFFICIAL_MOBILE_SERVICE] // 可选
    ],
];

$services = [
    '您的插件Web服务' => [
        'functions' => [
            'local_yourplugin_your_api_name'
        ],
        'restrictedusers' => 0,
        'enabled' => 1
    ]
];

服务注册键：

classname - 完整命名空间类名
methodname - 始终为 ‘execute’
type - ‘read’（SELECT）或 ‘write’（INSERT/UPDATE/DELETE）
ajax - 设置为true以允许AJAX/REST访问
capabilities - 必需的Moodle能力
services - 可选的服务包

步骤6：实现错误处理和日志记录

private static function log_debug($message) {
    global $CFG;
    $logdir = $CFG->dataroot . '/local_yourplugin';
    if (!file_exists($logdir)) {
        mkdir($logdir, 0777, true);
    }
    $debuglog = $logdir . '/api_debug.log';
    $timestamp = date('Y-m-d H:i:s');
    file_put_contents($debuglog, "[$timestamp] $message
", FILE_APPEND | LOCK_EX);
}

public static function execute($userid, $courseid) {
    global $DB;

    try {
        self::log_debug("API调用: userid=$userid, courseid=$courseid");
        
        // 验证参数
        $params = self::validate_parameters(self::execute_parameters(), [
            'userid' => $userid,
            'courseid' => $courseid
        ]);

        // 您的逻辑在这里
        
        self::log_debug("API成功完成");
        return $result;

    } catch (\invalid_parameter_exception $e) {
        self::log_debug("参数验证失败: " . $e->getMessage());
        throw $e;
    } catch (\moodle_exception $e) {
        self::log_debug("Moodle异常: " . $e->getMessage());
        throw $e;
    } catch (\Exception $e) {
        // 记录详细错误信息
        $lastsql = method_exists($DB, 'get_last_sql') ? $DB->get_last_sql() : '[N/A]';
        self::log_debug("致命错误: " . $e->getMessage());
        self::log_debug("最后SQL: " . $lastsql);
        self::log_debug("堆栈跟踪: " . $e->getTraceAsString());
        throw $e;
    }
}

错误处理最佳实践：

在try-catch块中包装逻辑
记录带时间戳和上下文的错误
捕获数据库错误的SQL查询
保留堆栈跟踪用于调试
记录后重新抛出异常

高级模式

复杂数据库操作

// 事务示例
$transaction = $DB->start_delegated_transaction();

try {
    // 插入记录
    $recordid = $DB->insert_record('your_table', $dataobject);
    
    // 更新相关记录
    $DB->set_field('another_table', 'status', 1, ['recordid' => $recordid]);
    
    // 提交事务
    $transaction->allow_commit();
} catch (\Exception $e) {
    $transaction->rollback($e);
    throw $e;
}

与课程模块协作

// 创建课程模块
$moduleid = $DB->get_field('modules', 'id', ['name' => 'quiz'], MUST_EXIST);

$cm = new \stdClass();
$cm->course = $courseid;
$cm->module = $moduleid;
$cm->instance = 0; // 将在活动创建后更新
$cm->visible = 1;
$cm->groupmode = 0;
$cmid = add_course_module($cm);

// 创建活动实例（例如，测验）
$quiz = new \stdClass();
$quiz->course = $courseid;
$quiz->name = '我的测验';
$quiz->coursemodule = $cmid;
// ... 其他测验字段 ...

$quizid = quiz_add_instance($quiz, null);

// 更新课程模块以包含实例ID
$DB->set_field('course_modules', 'instance', $quizid, ['id' => $cmid]);
course_add_cm_to_section($courseid, $cmid, 0);

访问限制（组/可用性）

// 通过组限制活动到特定用户
$groupname = 'activity_' . $activityid . '_user_' . $userid;

// 创建或获取组
if (!$groupid = $DB->get_field('groups', 'id', ['courseid' => $courseid, 'name' => $groupname])) {
    $groupdata = (object)[
        'courseid' => $courseid,
        'name' => $groupname,
        'timecreated' => time(),
        'timemodified' => time()
    ];
    $groupid = $DB->insert_record('groups', $groupdata);
}

// 添加用户到组
if (!$DB->record_exists('groups_members', ['groupid' => $groupid, 'userid' => $userid])) {
    $DB->insert_record('groups_members', (object)[
        'groupid' => $groupid,
        'userid' => $userid,
        'timeadded' => time()
    ]);
}

// 设置可用性条件
$restriction = [
    'op' => '&',
    'show' => false,
    'c' => [
        [
            'type' => 'group',
            'id' => $groupid
        ]
    ],
    'showc' => [false]
];

$DB->set_field('course_modules', 'availability', json_encode($restriction), ['id' => $cmid]);

带标签的随机问题选择

private static function get_random_questions($categoryid, $tagname, $limit) {
    global $DB;
    
    $sql = "SELECT q.id
            FROM {question} q
            INNER JOIN {question_versions} qv ON qv.questionid = q.id
            INNER JOIN {question_bank_entries} qbe ON qbe.id = qv.questionbankentryid
            INNER JOIN {question_categories} qc ON qc.id = qbe.questioncategoryid
            JOIN {tag_instance} ti ON ti.itemid = q.id
            JOIN {tag} t ON t.id = ti.tagid
            WHERE LOWER(t.name) = :tagname
              AND qc.id = :categoryid
              AND ti.itemtype = 'question'
              AND q.qtype = 'multichoice'";
    
    $qids = $DB->get_fieldset_sql($sql, [
        'categoryid' => $categoryid,
        'tagname' => strtolower($tagname)
    ]);
    
    shuffle($qids);
    return array_slice($qids, 0, $limit);
}

测试您的API

1. 通过Moodle Web服务测试客户端

启用web服务：站点管理 > 高级功能
启用REST协议：站点管理 > 插件 > Web服务 > 管理协议
创建服务：站点管理 > 服务器 > Web服务 > 外部服务
测试功能：站点管理 > 开发 > Web服务测试客户端

2. 通过curl

# 首先获取令牌
curl -X POST "https://yourmoodle.com/login/token.php" \
  -d "username=admin" \
  -d "password=yourpassword" \
  -d "service=moodle_mobile_app"

# 调用您的API
curl -X POST "https://yourmoodle.com/webservice/rest/server.php" \
  -d "wstoken=YOUR_TOKEN" \
  -d "wsfunction=local_yourplugin_your_api_name" \
  -d "moodlewsrestformat=json" \
  -d "userid=2" \
  -d "courseid=3"

3. 通过JavaScript（AJAX）

require(['core/ajax'], function(ajax) {
    var promises = ajax.call([{
        methodname: 'local_yourplugin_your_api_name',
        args: {
            userid: 2,
            courseid: 3
        }
    }]);

    promises[0].done(function(response) {
        console.log('成功:', response);
    }).fail(function(error) {
        console.error('错误:', error);
    });
});

常见陷阱和解决方案

1. “函数未找到”错误

解决方案：

清除缓存：站点管理 > 开发 > 清除所有缓存
验证services.php中的函数名是否完全匹配
检查命名空间和类名是否正确

2. “检测到无效参数值”

解决方案：

确保参数类型在定义和使用之间匹配
检查必需与可选参数
验证嵌套结构定义

3. SQL注入漏洞

解决方案：

始终使用占位符参数（:paramname）
切勿将用户输入连接到SQL字符串中
使用Moodle的数据库方法：get_record()、get_records()等

4. 权限被拒绝错误

解决方案：

在execute()中尽早调用self::validate_context($context)
检查必需能力是否匹配用户的权限
验证用户在上下文中有角色分配

5. 事务死锁

解决方案：

保持事务简短
始终在finally块中提交或回滚
避免嵌套事务

调试清单

[ ] 检查Moodle调试模式：站点管理 > 开发 > 调试
[ ] 查看web服务日志：站点管理 > 报告 > 日志
[ ] 检查自定义日志文件在$CFG->dataroot/local_yourplugin/
[ ] 使用$DB->set_debug(true)验证数据库查询
[ ] 测试管理员用户以排除权限问题
[ ] 清除浏览器缓存和Moodle缓存
[ ] 检查服务器上的PHP错误日志

插件结构清单

local/yourplugin/
├── version.php                 # 插件版本和元数据
├── db/
│   ├── services.php           # 外部服务定义
│   └── access.php             # 能力定义（可选）
├── classes/
│   └── external/
│       ├── your_api_name.php  # 外部API实现
│       └── another_api.php    # 附加API
├── lang/
│   └── en/
│       └── local_yourplugin.php  # 语言字符串
└── tests/
    └── external_test.php      # 单元测试（可选但推荐）

真实实现示例

简单读API（获取测验尝试）

<?php
namespace local_userlog\external;

defined('MOODLE_INTERNAL') || die();
require_once("$CFG->libdir/externallib.php");

use external_api;
use external_function_parameters;
use external_single_structure;
use external_value;

class get_quiz_attempts extends external_api {
    public static function execute_parameters() {
        return new external_function_parameters([
            'userid' => new external_value(PARAM_INT, '用户ID'),
            'courseid' => new external_value(PARAM_INT, '课程ID')
        ]);
    }

    public static function execute($userid, $courseid) {
        global $DB;

        self::validate_parameters(self::execute_parameters(), [
            'userid' => $userid,
            'courseid' => $courseid
        ]);

        $sql = "SELECT COUNT(*) AS quiz_attempts
                FROM {quiz_attempts} qa
                JOIN {quiz} q ON qa.quiz = q.id
                WHERE qa.userid = :userid AND q.course = :courseid";

        $attempts = $DB->get_field_sql($sql, [
            'userid' => $userid,
            'courseid' => $courseid
        ]);

        return ['quiz_attempts' => (int)$attempts];
    }

    public static function execute_returns() {
        return new external_single_structure([
            'quiz_attempts' => new external_value(PARAM_INT, '测验尝试总数')
        ]);
    }
}

复杂写API（从类别创建测验）

参见附带的create_quiz_from_categories.php以获取全面示例，包括：

多个数据库插入
课程模块创建
测验实例配置
带标签的随机问题选择
基于组的访问限制
广泛的错误日志记录
事务管理

快速参考：常见Moodle表

表	用途
`{user}`	用户账户
`{course}`	课程
`{course_modules}`	课程中的活动实例
`{modules}`	可用活动类型（测验、论坛等）
`{quiz}`	测验配置
`{quiz_attempts}`	测验尝试记录
`{question}`	问题库
`{question_categories}`	问题类别
`{grade_items}`	成绩簿项目
`{grade_grades}`	学生成绩
`{groups}`	课程组
`{groups_members}`	组成员资格
`{logstore_standard_log}`	活动日志

附加资源

指南

始终使用validate_parameters()验证输入参数
在操作前检查用户上下文和能力
使用参数化SQL查询（切勿字符串连接）
实施全面的错误处理和日志记录
遵循Moodle命名约定（小写、下划线）
清晰记录所有参数和返回值
用不同的用户角色和权限测试
对于写操作考虑事务安全
在服务注册更改后清除缓存
保持API方法聚焦且单一目的