
关于
指导为 Moodle LMS 创建自定义外部 Web 服务 API,遵循 Moodle 的外部 API 框架和编码标准。
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遵循严格的三方法模式:
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 {
// 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"
兼容工具
Claude CodeCursor
标签
后端开发
