---

name: moodle-external-api-development description: "本技能指导你为Moodle LMS创建自定义外部Web服务API，遵循Moodle的外部API框架和编码标准。" risk: unknown source: community date_added: "2026-02-27"

Moodle外部API开发

本技能指导你为Moodle LMS创建自定义外部Web服务API，遵循Moodle的外部API框架和编码标准。

何时使用本技能

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

核心架构模式

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

1. execute_parameters() - 定义输入参数结构
2. execute() - 包含业务逻辑
3. 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 {
    
    // Three required methods will go here
    
}

要点：

• 类必须继承 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, 'User ID', VALUE_REQUIRED),
        'courseid' => new external_value(PARAM_INT, 'Course ID', VALUE_REQUIRED),
        'options' => new external_single_structure([
            'includedetails' => new external_value(PARAM_BOOL, 'Include details', VALUE_DEFAULT, false),
            'limit' => new external_value(PARAM_INT, 'Result limit', VALUE_DEFAULT, 10)
        ], 'Options', 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;
    
    // 参数验证（必需！）
    $params = self::validate_parameters(self::execute_parameters(), [
        'userid' => $userid,
        'courseid' => $courseid,
        'options' => $options
    ]);
    
    // 上下文和权限检查
    $context = \context_course::instance($params['courseid']);
    self::validate_context($context);
    require_capability('local/yourplugin:view', $context);
    
    // 业务逻辑
    $result = $DB->get_record('user', ['id' => $params['userid']], '*', MUST_EXIST);
    
    return [
        'id' => $result->id,
        'fullname' => fullname($result),
        'email' => $result->email
    ];
}

步骤4：定义返回结构

public static function execute_returns() {
    return new external_single_structure([
        'id' => new external_value(PARAM_INT, 'User ID'),
        'fullname' => new external_value(PARAM_TEXT, 'Full name'),
        'email' => new external_value(PARAM_TEXT, 'Email address')
    ]);
}

步骤5：注册服务

文件：/local/yourplugin/db/services.php

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

$functions = [
    'local_yourplugin_your_api_name' => [
        'classname' => 'local_yourplugin\external\your_api_name',
        'description' => 'Get user information for a course',
        'type' => 'read',
        'ajax' => true,
        'capabilities' => 'local/yourplugin:view',
        'services' => [MOODLE_OFFICIAL_MOBILE_SERVICE],
    ],
];

类型选项：

• read - 只读操作
• write - 修改数据的操作

步骤6：升级版本

文件：/local/yourplugin/version.php

<?php
defined('MOODLE_INTERNAL') || die();
$plugin->version = 2026012700;
$plugin->requires = 2024042200;
$plugin->component = 'local_yourplugin';

安全最佳实践

• 始终调用 self::validate_parameters()
• 始终调用 self::validate_context()
• 使用 require_capability() 检查权限
• 永远不要信任用户输入——使用参数类型进行清理
• 对数据库查询使用参数化查询（$DB->get_record() 等）

测试

# 通过curl测试（需要有效token）
curl "https://yourmoodle.com/webservice/rest/server.php?wstoken=TOKEN&wsfunction=local_yourplugin_your_api_name&moodlewsrestformat=json&userid=2&courseid=1"