简介基于ThinkPHP5构建的小区物业管理系统面向PHP初/中级开发者、毕业设计学生及需要快速搭建物业后台的人员提供一套前后端完整的可运行项目源码。系统覆盖业主档案、收费管理、报修工单、公告发布等常用业务代码按控制器、模型、视图分层便于理解ThinkPHP5的MVC开发流程。资源包共2000个文件总体积25.98MB以php后台逻辑、js交互脚本、html模板、css/less样式居多另含数据库sql脚本、图片图标及配置文件结构完整可直接导入部署。目前已有868人学习下载既可作为课程设计或毕业设计的项目参考也能作为企业物业系统二次开发的基座帮助使用者节省从零搭建的时间同时熟悉FastAdmin等典型后台框架的目录组织方式。1. 为什么小区物业管理系统还会继续用 ThinkPHP5 而不是换框架接到一个小区物业管理系统时我大概率不会去追新框架。先看现状5 年前的项目ThinkPHP5.1PHP 7.4几十张表代码不规整但能跑。这时候谈重写不现实最稳的做法是顺着这套 TP5 的惯例把状态续上。这套系统要管业主、房间、费用、保修工单业务不算难但权限链条长、时间跨度大框架选型决定了后续维护成本。ThinkPHP5 的成熟在于文档多、一线 PHP 工程师熟悉容器和 ORM 也够用。我一般会从建表、模型、路由到并发缴费完整走一遍把 TP5 能复用的能力都榨出来。2. ThinkPHP5 小区物业的数据模型表结构、模型关联与查询参数2.1 房间、业主、费用这三张表才是 TP5 配置的起点小区物业系统模块多建表顺序需要按基础数据、业务数据划分。我一般先建house、owner、fee_bill三张表后续工单、巡检都能挂在它们下面。TP5 的模型和数据库层对表名、主键有默认约定表名用复数小写加下划线主键是id如果表里出现create_time、update_time且模型开了自动时间戳框架会在写入时自动维护。先把这些约定定下来后面查询代码写出来的风格才一致。CREATE TABLE house ( id int(11) unsigned NOT NULL AUTO_INCREMENT, building varchar(20) NOT NULL DEFAULT , unit varchar(20) NOT NULL DEFAULT , room_no varchar(20) NOT NULL DEFAULT , owner_id int(11) unsigned DEFAULT NULL, area decimal(8,2) DEFAULT 0.00, status tinyint(1) DEFAULT 0, create_time int(11) NOT NULL DEFAULT 0, update_time int(11) NOT NULL DEFAULT 0, PRIMARY KEY (id), KEY idx_owner (owner_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; CREATE TABLE owner ( id int(11) unsigned NOT NULL AUTO_INCREMENT, name varchar(30) NOT NULL DEFAULT , mobile varchar(20) NOT NULL DEFAULT , id_card varchar(18) NOT NULL DEFAULT , status tinyint(1) DEFAULT 1, create_time int(11) NOT NULL DEFAULT 0, update_time int(11) NOT NULL DEFAULT 0, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; CREATE TABLE fee_bill ( id int(11) unsigned NOT NULL AUTO_INCREMENT, house_id int(11) unsigned NOT NULL, fee_type tinyint(1) NOT NULL DEFAULT 0 COMMENT 1物业 2水费 3电费, total_amount decimal(10,2) NOT NULL DEFAULT 0.00, paid_amount decimal(10,2) NOT NULL DEFAULT 0.00, status tinyint(1) DEFAULT 0 COMMENT 0未缴 1已交 2退款, bill_month int(6) NOT NULL, create_time int(11) NOT NULL DEFAULT 0, update_time int(11) NOT NULL DEFAULT 0, PRIMARY KEY (id), KEY idx_house_month (house_id, bill_month) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这里把create_time和update_time设成 intTP5 模型可以在写入时自动维护字段名和类型都要对齐框架默认规则。owner_id放在房间表而不是业主表里因为一户业主可能有多套房反过来以后还要处理业主变更。fee_bill的bill_month用 int(6) 存比如202504不要用字符串排序和范围查询更快。这张表用(house_id, bill_month)做联合索引缴费查询最常用到的过滤条件就是这两列。表设计时容易踩的坑把业主信息直接冗余到缴费流水里。开始时方便但业主手机号变更后历史账单的旧号码改起来要全表更新。TP5 模型里用关联查询就能拿到业主信息冗余只在字段特别频繁读且不经常改时才考虑。公司项目里如果存在表前缀需要在database.php里配置prefix pm_模型里写表名house时实际访问的是pm_house同一套代码在不同环境可以通过改配置切换。2.2 用 ThinkPHP5 模型定义 hasOne、hasMany 和 belongsTo模型层我一般单独放application/common/model控制器不直接写Db::table。原因是物业系统后期报表多模型里定义好的关联可以被不同模块复用。比如House模型里把业主关系、账单关系都定义好房管、收费、报表三个模块都能直接调用不用每个控制器重新写一遍 JOIN。?php namespace app\common\model; use think\Model; class House extends Model { protected $name house; protected $autoWriteTimestamp true; public function owner() { return $this-belongsTo(Owner::class, owner_id); } public function feeBills() { return $this-hasMany(FeeBill::class, house_id); } }?php namespace app\common\model; use think\Model; class FeeBill extends Model { protected $name fee_bill; protected $autoWriteTimestamp true; public function house() { return $this-belongsTo(House::class, house_id); } }autoWriteTimestamp设为 true 后TP5 会在插入和更新时自动写create_time和update_time前提是表里字段名匹配。belongsTo表示当前表的外键指向目标表的主键hasMany表示目标表通过外键关联当前表的多个记录。定义关联时外键一定要写清楚TP5 虽然能通过表名推断但物业系统的表名普遍短推断容易出错。控制器里要查某栋楼的未缴费用关联查询应该是这样的use app\common\model\House; $list House::with([feeBills function ($query) { $query-where(status, 0)-order(bill_month, desc); }])-where(building, 3栋)-paginate(10); foreach ($list as $house) { foreach ($house-fee_bills as $bill) { echo $bill-bill_month . 欠费 . $bill-total_amount; } }with指定了预加载关联避免在 foreach 里逐条查询产生 N1 问题闭包里的条件挂在 feeBills 查询上不会影响外层 house 查询。TP5 模型返回的对象字段名默认用下划线风格和数据库名保持一致。这里的分页是外层分页内层关联默认不分页如果需要按账单分页应该反过来从FeeBill模型入口查询。关联场景结果关系TP5 方法房间有一个人所有人多对一belongsTo一人有多套房一对多hasMany某业主今年缴费记录一对多hasMany2.3 控制器里查费用清单链式查询和分页参数控制器接收参数后不要直接把全部条件拼进 SQL。TP5 的查询构造器支持where数组也支持paginate的分页参数自动获取。以账单管理为例public function index() { $params $this-request-get(); $query FeeBill::where(status, 0); if (!empty($params[building])) { $query-whereHas(house, function ($q) use ($params) { $q-where(building, $params[building]); }); } if (!empty($params[fee_type])) { $query-where(fee_type, $params[fee_type]); } $data $query-paginate(15); $this-assign(data, $data); return $this-fetch(); }whereHas在 TP5.1 里是标准的关联条件查询它会转换成 EXISTS 子查询比先把子查询结果 IN 进来更可控。页面上只需要把{$data|raw}输出分页链接TP5 的 paginate 会把 page 参数自动带上。索引列被函数包裹时才不会命中所以bill_month直接等于传参别做DATE_FORMAT之类的处理。分页里的 15 是每页条数页面传page2会由框架自动读取。若想限制单页最大条数可以在模型里重写paginate或使用listRows传参。这里没有用Db::query手写 SQL因为后续要加权限过滤时模型链式操作更方便拼条件。提示TP5 的字段缓存如果没刷新新加的字段可能查不到在部署环境执行php think optimize:schema可以生成数据表字段缓存避免这个问题。3. 用 ThinkPHP5 控制器和路由撑起物业缴费功能3.1 控制器分层基础控制器、业主端、后台端TP5 的目录结构天然支持按模块划分。5.0 是application/admin、application/api5.1 多了controller下的子目录。我通常建议用子目录而非独立模块因为大量物业接口要同时访问同一套公共模型模块堆多了反而增加公共文件的加载路径。基础控制器app\common\controller\BaseController负责初始化登录态。?php namespace app\common\controller; use think\Controller; use think\facade\Session; class BaseController extends Controller { protected $currentUserId 0; protected function initialize() { parent::initialize(); $this-currentUserId Session::get(user_id); } }后台控制器继承BaseController后每个方法里直接判断currentUserId。TP5 的initialize()在控制器构造后、操作前执行适合做统一的登录态初始化但不适合做请求级过滤器过滤器交给中间件更干净。一个常见误用是在初始化里写 AJAX 响应返回结果会让所有子类方法执行两遍逻辑正确的做法是初始化只赋值具体拦截交给路由中间件或check方法。业主端控制器可以单独放application/api/controller/owner后台放application/api/controller/admin两者都继承同一个基础控制器。子目录越多命名空间越长但类名冲突的概率越低。控制器本身应该薄一点业务逻辑放到模型或服务类里否则一个缴费方法能写两百行后面接手的人很难分清哪些参数是业务规则、哪些是自己定的临时变量。3.2 路由定义从 URL 到缴费接口映射TP5 路由文件在route/route.php开启路由后URL 访问和参数书写需要一起规范。常见做法是定义一个资源路由再加一个自定义缴费路由Route::group(api/v1, function () { Route::resource(houses, api/house); Route::post(bills/pay, api/bill/pay); })-middleware([app\http\middleware\ApiAuth]);资源路由会自带 index/create/read/update/delete业务不全都套用所以缴费这么明确的动作别用put去改账单。用Route::post显式声明语义比Route::put清楚。这里给整组分了ApiAuth中间件业主端和管理端在某些 action 上还要再单独加角色判断。路由分组的另一个好处是版本升级时把api/v1改成api/v2就能保留老接口的路由规则方便物业端和小程序端各自迭代。路由不生效时先看config/app.php里的url_route_on是否打开再查public/.htaccess里的伪静态配置很多 TP5 项目迁移服务器后出现 404都是伪静态规则没带 index.php。如果接口必须兼容旧客户端可以在路由规则后面加[method post]把请求方式限制死避免 GET 请求也能触发缴费这种危险动作。3.3 参数校验用 TP5 的 validate 在控制器里拦下脏数据TP5 提供独立的验证器放在application/api/validate/BillValidate.php?php namespace app\api\validate; use think\Validate; class BillValidate extends Validate { protected $rule [ house_id require|number|egt:0, fee_type require|in:1,2,3, amount require|float|gt:0, bill_month require|regex:/^\d{6}$/, ]; protected $message [ house_id.require 请选择房间, fee_type.in 费用类型错误, amount.gt 金额必须大于 0, bill_month.regex 账单月份格式错误, ]; }在控制器里调用public function pay() { $validate new BillValidate(); if (!$validate-check($this-request-post())) { return json([code 1, msg $validate-getError()]); } // 后续缴费业务逻辑 }注意bill_month用正则^\d{6}$而不是date因为有的系统允许跨年补缴严格日期校验反而会把历史账单挡在门外。amount用float|gt:0而不是number因为金额可能带两位小数number只接受整数。验证器返回的错误信息直接给前端展示还不够线上环境最好同时记录到日志方便排查是客户端传参有问题还是旧版本小程序还在发老格式。TP5 的验证器还支持场景比如同一个验证器在生成订单和退款时使用不同规则。但物业系统缴费和退款字段差异大我一般会拆成两个验证器而不是硬塞进同一个场景里。这样代码更直白新人接手时不用先找场景定义。4. 并发缴费与权限控制ThinkPHP5 事务、锁和中间件实战4.1 中间件做物业权限检查登录与角色在 TP5.1 中中间件类在app/http/middleware/CheckAdmin.php?php namespace app\http\middleware; class CheckAdmin { public function handle($request, \Closure $next) { $session $request-session(); if (!$session-has(user_id)) { return json([code 401, msg 请先登录]); } if ($session-get(role) ! admin) { return json([code 403, msg 无权限]); } return $next($request); } }handle的第一个参数是$request第二个是闭包。返回$next($request)表示继续执行控制器在这里拦截后返回值会直接作为响应。角色判断写在这里比写在控制器里好业务控制器只处理账单和费用不关心来源是网页端还是小程序端。中间件挂在路由分组上比如退款接口、费率设置接口都走这里。Route::group(admin, function () { Route::post(bill/refund, admin/bill/refund); })-middleware(\app\http\middleware\CheckAdmin::class);如果某些接口只允许指定房间的业主操作不能在全局中间件里写死。常见做法是中间件只确认登录操作者是当前房子的owner_id再放到控制器里比对。比如业主查询自家明细需要先查House表的owner_id是否等于Session::get(user_id)不等就返回 403。这个校验要放在事务外层避免还没确定权限就先开启事务浪费数据库连接。4.2 缴费入账用事务订单表与台账表的一致性物业缴费涉及到“生成订单”和“物业费台账更新”两个写入必须在一个事务里。TP5.1 的事务有两种方式链式和闭包。链式适合跨多个函数的事务闭包适合单方法收口。闭包的好处是代码块结束自动提交异常出现自动回滚不会出现漏写 commit。use think\facade\Db; Db::transaction(function () use ($billId, $payAmount) { $bill FeeBill::lock(true)-find($billId); if (!$bill || $bill-status ! 0) { throw new \Exception(账单状态异常); } $orderNo PM . date(YmdHis) . mt_rand(1000, 9999); Db::name(payment_order)-insert([ order_no $orderNo, bill_id $billId, amount $payAmount, status 1, pay_time time(), ]); Db::name(fee_bill)-where(id, $billId)-update([ status 1, paid_amount $payAmount, update_time time(), ]); });lock(true)是核心先给账单行加排它锁直到事务提交。若两个请求同时交同一张账单第二个请求的find会被阻塞第一个提交后它再读到的 status 已经是 1从而走异常分支。这里不能把订单插入和更新账单反过来否则锁等待和死锁概率会更高。payAmount这个变量应该来自支付回调而不是客户端传的值常见错误是直接用前端参数覆盖数据库金额导致任意金额支付入库审计时会非常被动。事务内尽量只做数据库操作不要调用远程支付接口。支付网关回调到系统时系统再开事务入账如果在事务里调用 HTTP 接口接口超时会长时间持有数据库锁拖垮整个缴费模块。锁的粒度也需要注意lock(true)加在单行上没问题但如果在查询列表上加锁会把一批账单都锁住影响其他正常缴费。4.3 排查 TP5 慢查询和锁等待的常用方法TP5 的调试模式可以在config/app.php开启app_debug true页面底部会显示执行日志。开不了调试模式的场景可以手动打开 SQL 监听Db::listen(function ($sql, $time, $explain) { if ($time 1000) { \think\facade\Log::record($sql . [ . $time . ms]); } });Db::listen是全局监听器建议放在公共基础控制器的initialize里。上线后app_debug必须关但Db::listen对接口影响不大可以保留。日志里看到超过 1 秒的 SQL先看有没有慢在关联查询上常见原因是关联表的索引缺失。排查锁等待用 MySQL 命令SHOW ENGINE INNODB STATUS;重点看LATEST DETECTED DEADLOCK部分。物业系统容易出现死锁的场景是多个请求同时更新同一栋楼多个房间更新顺序不一致。解决办法是在事务里固定更新顺序比如先按house_id升序再逐个更新。锁粒度适用场景说明行锁lock(true)单账单缴费并发下也能保证数据一致表锁月底批量出账出账期间不接受缴费适合低峰期乐观锁报修工单更新用版本号更新时间减少锁等待5. ThinkPHP5 和 ThinkPHP8物业代码迁移的差异排查清单5.1 升级前的差异对照表ThinkPHP5 到 ThinkPHP8 不是小版本升级影响最大的是 PHP 版本和容器调用方式。如果你要迁移小区物业系统与其看框架新特性不如先把 TP5 里经常出现的写法列出来。关注点ThinkPHP5 常见写法ThinkPHP8 更推荐的方向PHP 版本5.5 可跑需要 PHP 8.x 运行环境助手函数input(post.)用请求对象注入数据库名Db::name(fee)可用保留Db::name注意连接器配置控制器基类继承think\Controller多使用中间件和注解模型时间戳字段create_timeint 默认可配置为 datetime5.2 迁移时保留的兼容写法迁移最怕的是隐藏依赖。在动手前先全局搜索input(和I(这类助手函数在 ThinkPHP8 里优先级变低建议先改造成 Request 注入// 老代码 $houseId input(get.house_id); // 迁移时先这样做 $houseId $this-request-get(house_id);控制器里统一走$this-request后续重构控制器构造函数时能少改很多调用点。还有 TP5 默认把create_time存成 int迁移到 ThinkPHP8 后如果配置改成 datetime老数据导入导出时要多一步转换。建议迁移期间不要动字段类型先保持 int等业务侧全部走完再单独处理时间字段。5.3 一个验证迁移风险的技巧用php think run启动并遍历核心接口在路由最外层加一个只读观察中间件记录请求参数和 SQL 时间对比迁移前后接口响应时间。这不算硬编码只是为了迁移时不漏掉慢查询。重点观察缴费、账单列表、报修详情三个接口这三个能跑通其他模块大概率没问题。最后把runtime/cache缓存清理掉再重新执行composer dump-autoload避免类映射加载到旧的模型文件。本文还有配套的精品资源点击获取