moodle-external-api-development

Moodle External API Development - Moodle 自定义 Web 服务开发完整指南

技能概述

这是一个专为 Moodle LMS 开发者设计的技能，提供创建自定义外部 Web Service API 的完整解决方案，涵盖从参数验证到服务注册的全流程最佳实践。

适用场景

当您需要为本地或课程模块插件创建对外 API 时，使用本技能可以快速构建符合 Moodle 标准的外部函数。支持创建用于课程管理、用户数据同步、成绩查询等各类业务场景的 REST 接口。

如果您正在基于 Moodle 构建移动应用，本技能提供了创建后端 API 的完整方案。包括用户认证、课程数据获取、测验提交、成绩查询等常用接口的实现方法，以及与 Moodle Mobile Service 的集成指南。

当需要将 Moodle 与外部系统（如 HR 系统、ERP、数据分析平台）对接时，可以使用本技能创建安全的数据交换接口。涵盖参数验证、权限检查、SQL 防注入等安全最佳实践。

核心功能

严格遵循 Moodle external API 框架要求，实现 execute_parameters()、execute()、execute_returns() 三个核心方法。提供完整的参数类型定义（PARAM_INT、PARAM_TEXT、PARAM_BOOL 等）和返回结构配置（external_value、external_single_structure、external_multiple_structure）示例。

内置完整的安全检查流程，包括参数验证（validate_parameters）、上下文验证（validate_context）、能力检查（require_capability）以及 SQL 注入防护。提供事务管理、错误日志记录和异常处理的最佳实践代码示例。

详细说明 services.php 配置文件的编写方法，包括 classname、methodname、type、ajax、capabilities 等关键参数的设置。提供三种测试方式：Moodle Web Services 测试客户端、cURL 命令行、JavaScript AJAX 调用。

常见问题

如何在 Moodle 插件中创建自定义 web service？

创建 Moodle 自定义 web service 需要以下步骤：

类文件必须使用正确的命名空间（如 local_yourplugin\external）并包含安全检查 defined('MOODLE_INTERNAL') || die()。

Moodle web service 报 "Function not found" 错误怎么解决？

"Function not found" 是最常见的错误，解决步骤如下：

如果问题持续，可以开启调试模式（网站管理 > 开发 > 调试）查看详细错误信息。

Moodle 外部 API 如何进行权限检查和防止 SQL 注入？

Moodle external API 的权限检查和安全防护：

权限检查流程：

// 1. 获取上下文
$context = \context_course::instance($courseid);
self::validate_context($context);

// 2. 检查能力
require_capability('moodle/course:view', $context);

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

防止 SQL 注入：

错误处理：
使用 try-catch 块捕获异常，记录详细日志（包括 SQL 查询和堆栈跟踪），然后重新抛出异常以便上层处理。