前后端分离的课程表小程序：ThinkPHP接口源码解析与部署实践

简介基于ThinkPHP框架开发的小程序课程表源码采用前后端分离结构适合具备PHP和小程序基础的中级开发者也便于校园团队快速打造多校课程表应用。功能覆盖情侣空间、留言互动、互设课程表背景、个人日/周课表主题切换、教务系统课表一键导入、分享他人课表或单课、多校支持以及管理员配置的首页节日氛围既实用又兼顾社交场景。尤其情侣互动是特色通过关系绑定实现专属留言与背景互设适合校园社交类小程序产品化。压缩包约20.7MB包含4968个文件以PHP后端接口、JS前端逻辑为主搭配LESS/CSS样式、HTML模板、JSON配置和WXML/WXSS小程序页面文件类型齐全结构清晰。目前已有406人学习/下载足够说明其参考价值。全开源版本可直接部署运行便于研究课表解析、多校适配、情侣关系绑定等实现细节也可继续扩展自定义壁纸、留言提醒等玩法。1. 课程表小程序前后端分离这份 ThinkPHP 源码包到底能干什么如果你正在找一套能直接跑起来的课程表小程序而不是那种只有前端画了几个页面、后端接口全靠 mock 的演示项目那这份基于 ThinkPHP 的 v1.0.0 全开源版本地值得花几分钟看完。它最大的特点是前后端完全分离后端用 ThinkPHP 提供 JSON 接口前端是独立的小程序工程两者通过 HTTP 通信不依赖模板渲染也不存在把 PHP 代码塞进小程序的情况。这意味着你可以把这套代码同时当成「小程序前端模板」和「ThinkPHP 接口层参考实现」来用对于正在做毕业设计、接私活或者想快速搭一个课表管理工具的开发者来说这是非常少见的完整闭环。这套源码覆盖了课程表的典型业务闭环管理员或教师端维护课程数据小程序端按周次和节次展示课表支持用户绑定、课程增删改查等基础能力。全文我把它拆成了五个部分先讲后端接口与数据表设计再讲小程序端的请求封装与渲染逻辑然后给出本地部署步骤接着是五个高频踩坑点最后聊一个非常实用的技巧——如何把课表数据一键导入。如果你只是想要一个能跑通的 Demo按文章顺序操作一小时以内就能在开发者工具里看到真实数据。2. ThinkPHP 后端接口与数据表设计先搞清请求从哪来到哪去2.1 数据表结构课程表的核心不是课程而是「周次 × 节次 × 教室」的映射拿到源码后先别急着配数据库我建议你先把database目录下的 SQL 文件打开看一遍。课程表这类业务最忌讳把数据结构设计成「一张表存所有课程」因为课程天然带有时间维度同一门课可能第 1 周到第 16 周都在周五第 3 节上课但第 7 周停课一次。如果按简单字段存储后续做调课和周次判断时一定会写出又臭又长的条件查询。这份源码里典型的数据表是course表加上schedule表。course表存课程本身的固有信息比如课程名称、教师、学分、上课地点schedule表存具体的时间安排字段一般包括week_start、week_end、day_of_week、class_start、class_end还有course_id作为外键关联。这种设计的好处是查询某一天某一节的课表时只需要对schedule表做一次条件过滤然后 JOIN 课程表取详情不会出现一个课程在course表里存了十几条重复记录的情况。CREATE TABLE schedule ( id int(11) NOT NULL AUTO_INCREMENT, course_id int(11) NOT NULL COMMENT 关联course表, week_start tinyint(4) NOT NULL DEFAULT 1 COMMENT 开始周, week_end tinyint(4) NOT NULL DEFAULT 20 COMMENT 结束周, day_of_week tinyint(4) NOT NULL DEFAULT 1 COMMENT 星期几1-7, class_start tinyint(4) NOT NULL DEFAULT 1 COMMENT 开始节次, class_end tinyint(4) NOT NULL DEFAULT 2 COMMENT 结束节次, teacher varchar(50) DEFAULT COMMENT 任课教师, location varchar(100) DEFAULT COMMENT 上课地点, created_at int(11) DEFAULT NULL, updated_at int(11) DEFAULT NULL, PRIMARY KEY (id), KEY idx_course_id (course_id), KEY idx_week_day (week_start, day_of_week) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这里我重点解释两个容易被忽略的字段class_start和class_end存的是节次序号而不是时间字符串。比如class_start 1表示上午第一节课class_end 2表示到第二节课结束。前端拿到这两个数字后再去映射表里查对应的上课时间字符串比如「08:00 - 08:45」。这种做法的好处是如果学校调整作息时间只需要改前端的时间映射表完全不需要动数据库也不会出现「同一节课在 iOS 和 Android 上时间显示不一致」的尴尬。week_start和week_end的默认值我建议保持为 1 和 20这对应国内大多数高校的一学期 20 周。如果你接的是中小学项目改成 18 或 22 都可以但要注意前端的小程序端也要同步修改周次范围否则会出现「第 21 周有课但前端无法切换过去」的边界问题。2.2 接口路由设计RESTful 风格与 ThinkPHP 多应用模式的取舍这份源码的后端不是传统的单应用单控制器结构而是用了 ThinkPHP 的多应用模式。你可以理解为app目录下分了多个子应用比如admin管后台维护api管小程序请求。这样划分的核心原因是权限策略完全不同后台接口需要登录态校验小程序接口则通过 token 认证两者如果混在一个控制器里代码里会到处是if (isAdmin())这种判断时间长了根本维护不了。// route/api.php use think\facade\Route; Route::group(api, function () { Route::post(login, Login/login); Route::post(schedule/list, Schedule/list); Route::post(schedule/detail, Schedule/detail); Route::post(course/add, Course/add)-middleware(\app\middleware\Auth::class); Route::post(course/edit, Course/edit)-middleware(\app\middleware\Auth::class); Route::post(course/delete, Course/delete)-middleware(\app\middleware\Auth::class); });路由文件里的一个关键点是login和schedule/list不需要走Auth中间件因为用户还没有登录但涉及增删改的接口全部要经过Auth::class中间件校验。实际开发中我见过很多人把登录接口也加上登录校验结果小程序端永远无法完成首次登录这类问题排查起来非常浪费时间。如果你改了路由结构务必先在接口调试工具里逐个确认哪些接口需要 token。再单独说下schedule/list这个接口的入参设计。它接收三个参数week表示当前周day_of_week表示星期几user_id表示查看哪个学生的课表。为什么把user_id放在参数里而不是靠 token 解析因为课程表应用存在一种很常见的使用场景班长或者教务老师要帮别的学生查看课程冲突情况。如果接口强制从 token 里取账号身份这种场景就做不了。当然代价是任何人都能传别人的user_id查询数据所以源码里大概率是通过后台给每个用户分配可见范围来控制你自己做二次开发时要注意这个隐私边界。2.3 控制器与模型的协作别把 SQL 写在控制器里拿到源码后你可以重点看app/api/controller/Schedule.php这个文件。合格的 ThinkPHP 项目控制器里应该是「取参数 → 调模型方法 → 返回结果」三段式结构而不是堆砌Db::name(schedule)-where(...)-select()。这份源码基本遵循了模型层封装的规范。namespace app\api\controller; use app\api\model\Schedule as ScheduleModel; use think\response\Json; class Schedule { public function list(): Json { $week request()-post(week, 1); $day request()-post(day_of_week, 1); $userId request()-post(user_id, 0); $list ScheduleModel::getUserSchedule($userId, $week, $day); return json([ code 0, data $list ]); } }模型层的getUserSchedule方法内部再去拼条件包括 JOIN 课程表、过滤周次范围、按节次排序。这样分层之后的好处非常明显假如以后接口除了小程序端要用还要出一个管理后台的 Web 版控制器可以换一套写法但模型层的查询逻辑完全复用。而且模型方法里可以加缓存比如用 ThinkPHP 自带的Cache::remember把当天课表缓存五分钟有效缓解数据库压力。值得提醒的是课程表的查询条件里有一个容易搞错的点判断「当前周是否在某课程的时间范围内」时不能只写week week_start AND week week_end还需要考虑单双周的情况。比如某课程只在双周上课那即便在第 4 周双周范围内也要再加一个week % 2 0的条件。如果源码里没实现这个逻辑建议你自己加一个week_type字段值为 0 表示每周都上1 表示单周2 表示双周。这是课程表业务里最常见的隐藏需求不做的话期末总会有学生反馈「课表显示有课但实际没课」。3. 小程序端请求封装与课表渲染从接口数据到页面呈现3.1 请求封装统一处理 baseURL、token 和错误提示小程序端拿到源码后建议先看utils/request.js。这个文件相当于整个小程序前后端通信的中枢所有页面发起的请求都会经过它。如果这个文件的 baseURL 没配置对项目跑起来之后所有页面都会报「request:fail」。const BASE_URL http://127.0.0.1:8000/api; const request (url, method POST, data {}) { return new Promise((resolve, reject) { wx.request({ url: BASE_URL url, method: method, data: data, header: { Content-Type: application/json, Authorization: wx.getStorageSync(token) || }, success: (res) { if (res.data.code 0) { resolve(res.data.data); } else if (res.data.code 401) { wx.navigateTo({ url: /pages/login/login }); reject(new Error(登录已过期)); } else { wx.showToast({ title: res.data.msg, icon: none }); reject(new Error(res.data.msg)); } }, fail: (err) { wx.showToast({ title: 网络异常, icon: none }); reject(err); } }); }); };这段封装的逻辑重点在Authorization头。每次请求都会从本地缓存里取 token如果服务端校验失败返回 401前端直接跳到登录页。这里有一个实际开发中的坑微信小程序真机调试时127.0.0.1指向的是手机本身而不是你的电脑所以如果你在真机上调试必须把 BASE_URL 改成电脑在局域网内的 IP比如http://192.168.1.101:8000/api。开发者工具里可以直接填127.0.0.1但真机预览时一定要改这个问题几乎每个做过小程序联调的人都踩过。请求方式是 POST 还是 GET这份源码里主要用的是 POST。课程表查询参数不复杂POST 把参数放在 body 里也不会被浏览器缓存干扰。但要注意微信小程序的wx.request默认的Content-Type是application/json所以传给后端的参数必须是 JSON 对象如果你习惯用 PHP 的$_POST来接收这里需要统一改用request()-post()方法ThinkPHP 对 JSON body 的解析是自动支持的不需要额外设置。3.2 课表渲染Grid 布局还是 7 列循环课程表页面是整个小程序里最核心也最折磨人的页面。常见做法是把周一至周日作为横向表头上午下午作为纵向行然后根据课程节次计算单元格位置。源码里大概是用了wxss的 Grid 布局但如果你想去掉第三方 UI 库依赖可以直接用 CSS 的百分比宽度来模拟。view classtimetable view classrow wx:for{{tableData}} wx:keyindex view classtime-col{{item.timeText}}/view view classcourse-col wx:for{{item.courses}} wx:keycourseId wx:for-itemcourse block wx:if{{course}} view classcourse-card stylebackground: {{course.color}} text{{course.name}}/text text{{course.location}}/text /view /block block wx:else view classcourse-empty/view /block /view /view /view这里的tableData是一个二维数组第一维是节次比如上午 5 节、下午 4 节第二维是周一到周日七天。每个格子要么是空对象要么是课程详情。后端接口返回的数据通常是一维数组所以小程序端需要一个转换函数把一维课程数组映射到二维表格结构上。我建议把转换逻辑放在utils/schedule.js里单独维护不要在onLoad生命周期里写一大坨循环。转换时最需要处理的是跨节次问题一门课占了第 3 节和第 4 节渲染时应该让课程卡片撑满两行的高度。Grid 布局下实现这一点相对麻烦更省事的方案是把上午下午分开渲染上午一个表格、下午一个表格跨节次时卡片高度是行高的倍数。course.color字段是我自己在二次开发时加的。同一门课每周出现多次如果没有颜色区分视觉上很难快速定位。你可以给课程名做哈希取模映射一个颜色数组保证同一门课在周几都是同一种颜色。源码里没实现这个功能的话加一个randomColor函数即可工作量很小但体验提升非常明显。3.3 周次切换与当前周标识别让用户迷失在学期里课程表应用顶部通常有一个「第 X 周」的切换器左右滑动或点击按钮切换周次。源码里week这个状态一般放在页面的data里切换时重新调用schedule/list接口。关键点在于「当前周」从哪来我见过两种实现方式小程序端用new Date()结合开学日期计算或者后端接口返回。我更推荐后端返回因为如果学生在深夜打开应用前端用本地时间计算有可能因为时区设置问题导致周次偏差但后端统一用服务器时间就没有这个问题。function getCurrentWeek(startDate) { const now new Date(); const start new Date(startDate); const diff Math.floor((now - start) / (1000 * 60 * 60 * 24 * 7)); return diff 1; }这段代码的问题是它假设开学日期是某个周一如果开学日期是周三这个函数就不准确。实际项目里我会在数据库里配置学期开始时间然后后端计算周次时再做一次补偿算出 diff 后再判断now.getDay() start.getDay()如果当前星期数小于开学当天的星期数就减一周。这点细节容易被忽略但一旦出错学生看到的就是「课表上所有课程都错位了一周」这是非常致命的数据错误。周次切换器在 UI 上最好同时显示「本周」按钮点击后跳回当前周。因为学生翻到第 16 周查看考试安排后很可能忘了自己现在在第几周。这个功能看似简单但极大降低使用成本课堂上老师问「这是第几周」的时候学生打开小程序点一下「本周」就知道了这也是课程表类应用最有价值的功能之一。4. 本地部署全流程从数据库导入到开发者工具跑通4.1 环境准备PHP 版本与扩展检查部署 ThinkPHP 项目我强烈建议直接使用 PHP 8.0 以上的集成环境比如 PHPStudy 或 Laragon不要再用 PHP 5.6 或 7.0 去跑了。ThinkPHP 6 开始强制要求 PHP 7.2.5 以上源码如果是基于 ThinkPHP 6 或 8 开发的PHP 版本低了根本启动不了。先用php -v确认版本再确认pdo、mbstring、curl扩展是否开启。php -v php -m | grep -E pdo|mbstring|curl如果php -m输出里缺少pdo_mysql去php.ini里把对应的extensionpdo_mysql一行前面的分号去掉然后重启 PHP 服务。这个环节看起来基础但很多新手在部署时恰恰是卡在扩展没开启导致数据库连接报错「could not find driver」。ThinkPHP 还需要openssl扩展因为 token 生成和校验通常依赖加密函数没有这个扩展登录接口会直接 500。4.2 导入数据库与配置.env文件源码包里通常有一个sql或者database目录里面存放.sql文件。用 Navicat 或者命令行导入都可以导入后你要重点关注的是config/database.php和项目根目录下的.env文件。.env文件是 ThinkPHP 6 及以上版本读取数据库配置的核心它里面的配置优先级高于config/database.php所以如果改了config文件没生效八成是.env把你覆盖了。APP_DEBUG true [APP] DEFAULT_TIMEZONE Asia/Shanghai [DATABASE] TYPE mysql HOSTNAME 127.0.0.1 DATABASE timetable USERNAME root PASSWORD 123456 HOSTPORT 3306 CHARSET utf8mb4 PREFIX tp_这里有两个细节需要注意。第一是DATABASE名称要跟你实际导入的库名完全一致大小写也不能错Linux 环境下数据库名是区分大小写的。第二是PREFIX表前缀如果 SQL 文件里的表名是tp_schedule那么前缀就是tp_如果你导入时把表名前缀去掉了这里就要留空。表前缀不一致是部署后最常见的「表不存在」报错来源排查时先看报错信息里完整的表名。配置好.env后访问后端地址比如http://127.0.0.1:8000/api/schedule/list如果返回 JSON 格式的错误信息而不是 PHP 的 Fatal Error说明框架已经跑通。这里多说一句如果你用的是 PHP 内置服务器启动项目命令是这样的cd /path/to/project php think run默认启动端口是 8000如果你发现端口被占用可以用php think run -p 8080指定另一个端口。小程序端的 BASE_URL 也要对应改成 8080。另外注意php think run启动的是单线程开发服务器只适合本地调试上线部署建议用 Nginx PHP-FPM。4.3 小程序端导入与基础配置小程序端拿到的是一整个mp-weixin或miniprogram目录在微信开发者工具里选择「导入项目」然后填入自己的AppID。如果你没有小程序 AppID可以先用测试号但测试号有一个限制部分涉及登录的接口可能受临时域名白名单影响不能完全模拟真实环境。开发者工具里最需要修改的位置有三个utils/request.js的BASE_URL、app.js里可能存在的全局配置项、project.config.json里的appid字段。把BASE_URL改成你本地的后端地址后编译运行如果看到课表页面有数据说明前后端链路已经通了。如果请求显示 404先确认后端路由是http://127.0.0.1:8000/api/schedule/list而不是http://127.0.0.1:8000/schedule/list多一层api是路由分组前缀决定的不能去掉。微信开发者工具还有一个经常被忽略的设置在「详情 → 本地设置」里不校验合法域名。本地调试时必须勾选这个选项否则开发者工具会拦截对http://127.0.0.1的请求理由是「不在合法域名列表」。真机调试时同样要在开发设置里开启「不校验合法域名」否则真实手机上请求全部失败。这一点不算坑但确实是每次新拉代码调试时最容易漏掉的一步。5. 课程表小程序避坑指南五个让新人崩溃的典型问题5.1 接口返回 500 但没有任何错误信息现象请求schedule/list接口Postman 或者开发者工具里返回 500响应体是 HTML 或者一片空白。原因最常见的是开启了APP_DEBUG但.env里数据库配置错误或者 SQL 文件没有完整导入导致模型查询时表不存在。另一种可能是一个 PHP 语法错误被 ThinkPHP 的异常处理吞掉了只返回 500 状态码。解决先确认.env里的数据库名、用户名、密码和实际环境一致然后在app/ExceptionHandle.php里临时加日志输出或者直接用try catch包裹控制器里的查询代码、输出异常信息。更快的办法是打开 ThinkPHP 的trace调试模式在config/app.php里把trace true打开刷新请求后底部或响应头里会包含完整的异常链。5.2 小程序请求提示「url not in domain list」现象开发工具里编译报错错误提示为「url not in domain list」页面数据加载不出来。原因微信小程序为了保证安全性要求所有请求域名必须在小程序后台配置为合法域名但本地开发环境是 HTTP 且 IP 非法所以被拦截。解决开发调试阶段在微信开发者工具右上角「详情 → 本地设置」勾选「不校验合法域名」。如果你用真机预览也要在开发者工具「预览」按钮生成二维码前勾选同一项。这个操作只对开发板生效如果你要上线发布还是要配置 HTTPS 的正式域名并且在小程序管理后台添加 request 合法域名。5.3 周次切换后课程「无影无踪」或全部显示现象点击第 2 周课表显示为空点击第 1 周一切正常或者无论切到第几周都显示同样的课程。原因这属于课程表业务的经典逻辑错误。前者可能是week_start和week_end设置的过滤条件把第 2 周的课程排除了比如某课程只在单周开课但代码没判断单双周后者则可能是接口没有把week参数传到数据库查询条件里直接把所有课程都返回了。解决在小程序端的request封装里打印出实际发送的参数确认week的值确实传给了后端。然后在后端的ScheduleModel::getUserSchedule方法里输出最终的 SQL在 ThinkPHP 里用Db::getLastSql()查看查询语句检查where条件是否包含week_start 2 AND week_end 2。如果没包含就是模型方法里丢参数了。5.4 真机调试连不上本地后端现象在开发者工具里一切正常但用手机扫码预览后所有接口请求失败提示「request:fail」。原因手机和电脑不在同一个局域网或者BASE_URL里的 IP 是127.0.0.1。手机访问127.0.0.1指向的是手机自己不是你的电脑。解决把电脑和手机连到同一个 Wi-Fi然后在电脑上查局域网 IPWindows 用ipconfigmacOS 用ifconfig | grep inet。把BASE_URL里的127.0.0.1替换成电脑的局域网 IP并确保后端的php think run监听在0.0.0.0而不是默认回环地址。启动命令改成php think run -H 0.0.0.0 -p 8000手机才能通过局域网 IP 访问。5.5 课程表显示英文或乱码现象数据库里看到的中文正常但小程序里显示为乱码或者接口返回 JSON 里的中文变成\u5b66\u751f这样的转义序列。原因第一是数据库连接charset设置成了utf8而不是utf8mb4导致某些特殊字符比如 emoji无法存储第二是小程序端解析 JSON 时没有正确处理 Unicode 转义但wx.request默认就会自动解析所以更大概率是数据库字段排序规则问题。解决把.env里的CHARSET改成utf8mb4同时确认course表的ENGINEInnoDB DEFAULT CHARSETutf8mb4如果建表语句没加DEFAULT CHARSETutf8mb4用ALTER TABLE course CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;修正。乱码问题最好在建表时就解决数据一旦写入错误编码洗数据比改表结构麻烦十倍。6. 一个实用技巧用脚本批量导入课程表 JSON 数据手动在后台一条条添加课程非常痛苦尤其是一学期十几门课、每门课还有多个时间段。我一般会写一个 Python 脚本把 Excel 或 CSV 里的课程表转成接口需要的 JSON 格式然后一条条 POST 到课程添加接口。这套源码里没有自带导入功能但接口已经有了所以批量导入就变成了一个「读文件 → 转换格式 → 调接口」的简单脚本。import requests import json API_URL http://127.0.0.1:8000/api/course/add TOKEN your_token_here courses [ {name: 高等数学, teacher: 张老师, week_start: 1, week_end: 16, day_of_week: 1, class_start: 1, class_end: 2, location: A101}, {name: 大学英语, teacher: 李老师, week_start: 1, week_end: 16, day_of_week: 3, class_start: 3, class_end: 4, location: B203}, ] headers { Content-Type: application/json, Authorization: TOKEN } for course in courses: resp requests.post(API_URL, jsoncourse, headersheaders) result resp.json() if result.get(code) 0: print(f导入成功: {course[name]}) else: print(f导入失败: {course[name]} - {result.get(msg)})这段脚本的核心是构造courses列表每个元素对应一条要创建的课程记录字段必须跟后端模型验证规则一致。比如后端要求name必填、day_of_week在 1 到 7 之间脚本里不满足就会被接口拒绝。实际使用时我会从学校教务系统导出的 Excel 里读取数据pandas读出来之后做字段映射再把映射结果循环 POST。如果课程数量多建议每调 20 条就 sleep 一秒避免短时间高频请求触发后端限流或者数据库连接池耗尽。这个技巧的核心价值在于它把「给课程表小程序填充数据」从手工录入变成了半自动操作。小程序端本身只是一个展示壳子数据准不准、全不全直接决定用户愿不愿意用。所以不管你是给自己学校的课表做工具还是给客户做演示先想办法把真实数据批量灌进去比花时间调 CSS 样式重要得多。做完批量导入后还有一个验证习惯我强烈建议新手养成导入完成后用 SQL 语句查一遍schedule表的总记录数再随机抽查某一天的数据直接在数据管理器里看可视化结果。只有数据层确认无误前端展示才值得信任。从那以后我每次做课程表项目都会强制走一遍「批量导入 → SQL 抽查 → 小程序真机验证」的流程这三步走完基本不会出现让学生翻车的低级数据错误。希望这份拆解能让你在部署和二次开发这套 ThinkPHP 课程表小程序时少走弯路顺利跑通自己的版本。本文还有配套的精品资源点击获取