简介这是一份Unigui开源框架源码包主要面向具备Delphi基础、希望转向BSBrowser-Server架构应用开发的开发者。Unigui将桌面应用开发体验迁移到Web环境支持组件化拖拽、事件驱动、实时更新、多语言及多数据库集成可用一套代码覆盖PC和移动端。资源共90个文件、压缩包大小9.92MB核心包含28个pas源码、19个sql建库建表脚本、19个dfm窗体文件以及2份开发手册PDF和配套DOC文档便于对照源码理解框架调用方式、数据库设计和由Delphi工程搭建BS应用的完整思路。已有3596人学习下载。从源码和文档中可掌握Unigui的启动流程、窗体与服务端模块组织、常用封装函数和插件调用方法适合希望深入阅读开源项目、提升Web化Delphi开发能力的进阶学习者。1. Unigui开源框架为什么值得花时间参考学习一个做桌面运维系统多年的老团队突然要交付一个“能在浏览器里打开、手机上能用”的版本。重新写前端、再写接口、再联调至少一两个月。用Unigui开源框架把原来熟悉的Delphi界面代码稍作调整直接编译出一个Web应用一个周末就能拿出能演示的版本。我第一次看到这个效果时确实被震住了。Unigui的核心思路是用服务器端Delphi代码描述界面逻辑框架自动在浏览器端生成可交互页面。对整天和VCL控件打交道的开发者来说这几乎是零门槛的前端方案。这篇笔记会从运行时机制讲起到最小工程、数据绑定、避坑记录最后给出一套两周内的验证思路帮你看清它到底适合解决什么问题、不适合解决什么问题。2. 先看懂Unigui的运行时机制它到底是怎么把Delphi代码变成网页的2.1 浏览器里那层界面到底是谁渲染的Unigui不是把Delphi代码编译成JavaScript也不是把窗体绘成图片推给浏览器。它的模型是“客户端-服务器”双端协作服务器端保留完整的窗体对象树和组件状态浏览器端只维护一份由ExtJS生成的页面镜像。用户在浏览器里输入关键词、点击查询按钮触发的是ExtJS捕获的DOM事件。事件被序列化成一条AJAX请求发送到服务器服务器端找到这个会话对应的窗体实例调用你在Delphi里写的按钮点击事件处理器。事件处理器执行完毕后Unigui比较服务器端组件树的变化只把界面需要更新的增量部分返回给浏览器ExtJS再更新对应DOM节点。这就是Unigui和传统Web MVC最根本的差异。传统Web开发里每个请求都是无状态的服务器处理完就扔掉上下文。而Unigui里服务器端为每个在线用户维护一个完整的Delphi Application对象、窗体实例和数据模块浏览器只是它的显示器。理解这个机制后再看代码就清楚多了。下面是一个典型的Unigui按钮事件procedure TMainForm.UniButton1Click(Sender: TObject); begin // 服务器端执行浏览器端不会有任何逻辑 UniLabel1.Caption : 当前服务器时间 FormatDateTime(yyyy-mm-dd hh:nn:ss, Now); end;这段代码看起来和VCL里的ButtonClick没区别但执行位置完全不同。VCL里是本地CPU执行Unigui里是服务器CPU执行后再推送界面变化。所以Unigui应用的性能瓶颈通常在服务器端会话数越多内存和CPU消耗越大。这也是后续排障时需要时刻记住的大前提。2.2 状态保持与会话绑定Unigui和传统Web MVC的本质差异理解了渲染位置再来看看状态管理这是Unigui最容易被老Web开发者误解的地方。传统Web应用靠Cookie、Token或SessionID在无状态请求之间重建用户上下文而Unigui的状态直接驻留在服务器内存里。每一个浏览器连接会被分配一个独立的TUniSession对象。这个Session里挂着完整的Application、MainForm、DataModule以及你在窗体上放的所有组件实例。也就是说UniEdit1.Text的值、UniDBGrid1当前选中了哪一行、UniMemo1里积累了几条日志这些状态在服务器端都有一份真实副本。这种模型带来的最大好处是开发体验。用Unigui写业务逻辑不需要考虑序列化、JSON组装、REST接口设计。你操作的就是控件实例代码几乎是从VCL项目里复制粘贴过来的。代价则是服务器资源占用。所有在线用户的状态都堆在服务器内存里用户数上去以后内存会像吃水一样涨。数据库连接也不能像传统连接池那样临时获取、用完即还每个Session往往持有自己的连接或事务上下文。Unigui社区常见做法是Session的DataModule里持有连接对象并在Session销毁时统一释放。这种设计在几十人、几百人的内部系统里没有问题但如果目标是数千人同时在线就需要在架构层面做拆分。2.3 所谓“开源”参考学习的价值点在哪里严格来说Unigui本身是商业产品但它的源码包、Demo工程和框架设计对参考学习完全开放。我一般建议新人重点读两样东西一是官方Demo集合二是框架自带的源码目录。Demo集合的价值在于“对照业务场景找实现”。比如想实现主从表就打开MasterDetail示例想做权限登录就查看Login示例想了解文件上传看Upload示例。每个Demo都是一个小而完整的工程能直接编译运行。源码目录更值得花时间精读。Unigui的服务器端核心暴露了大量的类声明顺着TUniServerModule、TUniMainModule、TUniSession这几个类往下追能看清Session生命周期、AJAX请求分发、控件树同步的逻辑理解框架边界在哪里。我自己的习惯是遇到不确定能不能实现的交互先翻源码或Demo确认而不是直接问别人。这个习惯帮我避开了很多“想当然”的弯路。看源码时重点留意名字里带Request、Response、Command的单元这里面藏着前后端通信的完整链路。3. 跑通第一个Unigui应用环境配置、最小工程与三个必调参数3.1 安装与IDE集成装完之后先看哪个菜单Unigui的安装包会向Delphi IDE注入一组新菜单和控件页。安装完成后点新建工程菜单会出现两个常用工程模板一个是基于ISAPI的DLL类型另一个是独立服务器类型实际开发调试通常选独立服务器。独立服务器类型的优势是无需IIS或Nginx辅助编译后直接以exe运行默认监听一个HTTP端口。打开浏览器就能访问。这对于本地联调非常方便改完代码、编译、刷新页面即可。我一般会在安装后做两件事。第一件事是确认UniServerModule被自动加入工程这是全局配置中心。第二件事是打开Project Options里关于运行时主题的设置确认默认主题可以被浏览器正确加载。环境验证的常见做法是新建一个空窗体工程直接运行浏览器访问默认端口看到页面里出现一个空白窗体。能做到这一步环境就基本通了。3.2 最小可运行工程一个按钮、一个输入框、一次查询交互跑通环境后用最小工程理解Unigui的开发路径。在窗体上放一个TUniEdit、一个TUniButton、一个TUniMemo在按钮的OnClick事件里写查询逻辑。procedure TMainForm.UniButton1Click(Sender: TObject); begin // 文本框内容以UTF-8传回服务器端直接读取即可 if UniEdit1.Text then begin UniShowMessage(请输入查询关键词); Exit; end; // UniMemo是服务器端MemO控件追加内容后浏览器端自动更新 UniMemo1.Lines.Add(FormatDateTime(yyyy-mm-dd hh:nn:ss, Now) 开始查询 UniEdit1.Text); // 这里可以调用服务器端业务方法完成后更新界面 UniLabel1.Caption : UniEdit1.Text 查询完成; end;这段代码注释里藏着一个关键理解UniEdit1.Text的读取和UniLabel1.Caption的赋值都发生在服务器端内存里。浏览器端输入框的字符是通过AJAX请求传回服务器的服务器改完Caption后再把新的Caption内容推送回浏览器。写第一个工程时最需要适应的是“速度感”。由于每次交互都涉及一次HTTP往返操作响应会明显比桌面程序慢。这不是代码效率问题而是Unigui的工作方式决定的。如果页面里放了几千个控件每个控件的状态都要随请求同步响应自然会变慢。控制单页面的控件数量是Unigui性能调优的第一步。3.3 三个必调参数端口、会话超时、字符集UniServerModule里集中了核心运行参数。我每次新建工程第一个改的就是三个参数。第一个参数是服务端口。默认端口是8077但被占用是常事改成服务规划里固定的端口号。procedure TUniServerModule.UniServerModuleCreate(Sender: TObject); begin // 独立服务模式监听端口与反向代理配置保持一致 Self.Port : 8077; // Session超时时间单位秒。默认值往往偏长建议按业务调整 Self.SessionTimeout : 600; // 页面字符集统一为UTF-8避免中文乱码 Self.Charset : utf-8; // 标题会显示在浏览器标签页上 Self.Title : 某某管理系统; end;第二个参数是SessionTimeout。这个值决定用户关闭浏览器后服务器端内存里的Session还能活多久。设小了用户一个午饭时间回来可能被要求重新登录设大了僵尸Session占用内存。内部管理系统我一般设600秒左右配合心跳机制防止活跃用户被误杀。第三个参数是Charset。务必统一UTF-8同时保证服务器端文件保存编码和数据库连接编码一致。这个参数设不好后面中文乱码排查会浪费大量时间。这三个参数设好后工程就有了可运行的基础。再往下就要开始处理真正有业务含量的部分数据展示和交互。4. 把VCL式开发习惯迁移到Unigui数据绑定与界面交互实操4.1 用TUniDBGrid做数据展示和DBGrid的差异在哪里TUniDBGrid是Unigui项目里出镜率最高的控件它绑定DataSet的方式和VCL里的TDBGrid几乎一致放一个TDataSource指向TFDQuery或TClientDataSet再把TUniDBGrid的DataSource属性指向它。实际使用时有几个属性要特别留意。标准DBGrid里的ReadOnly行为在Unigui里语义略有不同Web端默认不开启就地编辑需要在TUniDBGrid的EditorOptions里显式配置。和桌面DBGrid最大的区别在于滚动加载桌面DBGrid滚动是即时绘制的UniDBGrid则每滚动一段距离都可能触发服务器请求所以大数据量场景必须开启分页。一个常见配置是// 设置UniDBGrid的分页属性避免一次加载全部数据 UniDBGrid1.Constraints.MaxWidth : 300; // 这是界面约束示例 // 更关键的分页设置在属性面板 // UniDBGrid1.WebOptions.Paged : True // UniDBGrid1.WebOptions.PageSize : 50PageSize设置成50比较均衡。每页少于30次多后端请求太频繁大于100时单次响应时间变长浏览器渲染也有压力。带复杂表单的项目PageSize用50起步后面再压测调整。另一个容易忽略的点是列宽。桌面端DBGrid的列宽由拖动决定浏览器端则要设置每列的Width属性否则浏览器窗口尺寸变化时列宽会表现得不可控。建议优先使用百分比宽度布局并给关键列设置Flexible属性。4.2 主从表联动与异步刷新把“重查整页”改成“重查局部”内部管理系统里的主从表页面用Unigui写起来和VCL非常接近。左边放主表TUniDBGrid右边放从表TUniDBGrid两个TFDQuery之间建立MasterSource关联。主表光标移动时从表自动刷新。这里要注意一个细节Unigui的主从联动默认是服务器端行为。主表记录滚轮的每一次移动都会触发从表查询。网络状态好时体感还行但网络抖动时会出现明显的等待感。常见优化方式是把主表的光标移动事件改成“选中后再加载从表”而不是边滚动边加载。procedure TMainForm.UniDBGrid1AfterLoadData(Sender: TObject); begin // 主表数据加载完成后手动刷新从表 qryDetail.Close; qryDetail.ParamByName(master_id).AsInteger : qryMaster.FieldByName(id).AsInteger; qryDetail.Open; end;主表点击事件里控制从表加载是避免复杂联动卡顿的惯用手法。把从表查询从“自动随光标联动”改成“选中时执行”响应次数的变化立竿见影。异步刷新是另一个值得养成的习惯。Unigui支持通过TUniTimer或AJAX回调局部刷新某个控件而不刷新整个页面。典型场景是顶部状态栏展示服务器时间或任务进度用定时器每5秒更新一次局部区域比整页刷新体验好得多。4.3 导出Excel与文件下载服务器端二进制流如何到达浏览器Web应用离不开文件导出。Unigui里实现下载比传统Web方案简单因为服务器端可以直接操作Session和Response。常见做法是在服务器端生成一个临时文件或MemoryStream然后调用UniSession的发送方法把数据作为HTTP响应返回浏览器端自动触发下载。procedure TMainForm.btnExportClick(Sender: TObject); var TmpPath: string; begin // 第一步生成导出文件到服务器临时目录 TmpPath : UniApplication.GetTempFile; // 典型做法是向UniApplication索取临时路径 // 第二步调用导出逻辑生成Excel或CSV内容 // 第三步发送给浏览器并指定下载文件名 // UniSession.SendFile(TmpPath, 导出数据.csv, text/csv); end;注意文件名最好用英文加时间戳组合避免浏览器对中文文件名处理不一致。服务器端生成的临时文件一定要在Session结束时清理否则临时目录会越积越满。这个坑在长时间运行的服务器上非常常见后续避坑章节会再提到。到这里Unigui开发的主流路径已经完整走通建工程、写界面、绑数据、导出文件。接下来必须面对现实中的各种意外。5. Unigui实战避坑记录五个最容易翻车的问题与排查方法5.1 Session内存只涨不降运行几天后服务器卡死现象应用刚启动时响应很快运行一两天后越来越慢内存占用持续走高重启后才恢复。原因Unigui的Session一直驻留在服务器内存里。业务代码里创建的TFDQuery、TMemoryStream、临时对象在事件结束后没有释放这些对象全部挂在Session生命周期上。Session不销毁内存永远不回收。另一个常见诱因是SessionTimeout设得太长或为0用户关闭浏览器后Session仍然存活数小时。解决先确认SessionTimeout是合理值再给全局DataModule的OnDestroy事件里做统一清理。调试阶段可以用UniServerModule的日志功能观察活跃Session数验证内存曲线和在线用户曲线是否匹配。procedure TUniMainModule.DataModuleDestroy(Sender: TObject); begin // Session销毁时统一释放全局连接和查询对象 FDConnection1.Connected : False; end;内存问题排查时我习惯在测试环境跑两个小时的固定脚本模拟操作同时记录内存曲线。如果曲线持续阶梯上升而不是到达平台期基本就是对象泄漏。5.2 中文内容提交后变成乱码或者页面显示问号现象浏览器里显示正常但数据提交后数据库里存的内容变成乱码或者反过来数据库里正常页面显示为问号。原因Unigui的Charset设置和数据库连接的字符集不一致。页面显示问号通常是响应头里的charset和页面实际编码不匹配数据库乱码则说明服务器端传给数据库的字节流编码有误。解决统一三层编码。UniServerModule.Charset设为UTF-8数据库连接字符串里指定字符集为UTF-8数据库表字段也使用UTF-8编码。三层统一后再乱码检查操作系统区域设置是否影响了文件的默认编码。// 数据库连接参数示例注意字符集设置与Unigui保持一致 FDConnection1.Params.Add(CharacterSetutf8);排查乱码时先定位是哪一层出问题。在按钮事件里把UniEdit1.Text写入服务器端日志如果日志里是正常中文而数据库乱码问题就在连接层如果日志里就已经乱码问题就在HTTP传输或IDE文件编码。5.3 并发用户一多请求排长队页面转圈现象测试阶段20人同时用没问题正式环境200人在线时页面操作明显卡顿部分请求直接超时。原因Unigui是服务器端密集计算模型。每个请求都要在服务器端找到对应的Session、执行事件处理器、序列化返回数据。服务器CPU和数据库连接池成为瓶颈。尤其是某些数据库组件默认给每个Session建立独立连接连接数翻倍必然超限。解决数据库连接必须使用连接池不能让每个Session各自持有独立长连接。同时用负载均衡把不同用户分散到多台服务器上。Unigui的Session亲和性决定了如果部署在多机环境反向代理必须开启会话保持否则用户请求被路由到另一台机器Session找不到直接跳回登录页。并发排查首先要看数据库慢查询。Unigui项目里很多卡顿不是框架本身慢而是某个查询没有索引加上网络往返放大。5.4 用户按F5刷新页面后还在登录状态但界面状态全丢了现象用户正常登录使用不小心按了浏览器刷新按钮页面重新加载当前表单里填了一半的内容全部清空。原因Unigui的工作方式是增量交互。用户输入的内容实时在服务器端有记录但浏览器刷新会重新拉取整个页面初始化脚本而服务器端Session里的状态还保留着。界面状态和浏览器页面呈现出现了同步断裂。解决尽量避免引导用户使用浏览器刷新。重要页面可以设置当用户关闭页面或刷新时弹出提醒。更稳妥的做法是在关键业务页面做草稿保存将表单关键字段自动存到服务器端。// 关键表单的常用保护方式定时自动保存表单内容 procedure TMainForm.UniTimer1Timer(Sender: TObject); begin // 每60秒把UniEdit内容暂存到Session变量崩溃后可恢复 FFormDraft : UniEdit1.Text; end;F5问题没有完美解只有缓解措施。熟手的选择是业务型页面弱化刷新功能并在导航流程上引导用户使用系统内部按钮跳转。5.5 部署到反向代理后面登录跳转后莫名丢失会话现象本机直接访问一切正常部署到Nginx或Apache通过域名访问后登录成功后跳转几百毫秒又回到登录页。原因Unigui窗体里保存了两个URL相关的状态当前请求路径和服务器端口。经过反向代理后浏览器实际访问的是80端口而Unigui内部记录的端口可能是实际监听端口导致Session关联的URL不匹配。解决在UniServerModule里配置反向代理环境下的路径和端口一致性确保框架获取到的请求地址与实际一致。部署时还必须在会话超时策略里为代理层增加“强调Cookie Secure开关”一类的设置。// 反向代理场景下的关键配置示例 Self.Port : 80; // 把Unigui监听端口配置成代理暴露的端口 Self.CookiePath : /; Self.CookieSecure : False; // 如果代理负责HTTPS终结Cookie应允许HTTP传输反向代理问题排查看日志最快。把Unigui的日志级别调到调试查看登录跳转时的请求URL和Set-Cookie响应头通常一眼就能看出端口或路径不匹配。6. 验证Unigui是否适合你的团队两周试做法与决策边界判断一个技术值不值得投入最有效的方法是做一个贴近真实业务的横向对比而不是听评价。用一个两周的试做路径帮你拿到第一手数据。试做建议分三段。前四天跑通官方Demo并复刻现有系统的一个真实页面比如登录页加主列表但不要只做美术还原要把数据库连接、查询、翻页、导出都做进去。第五天到第七天模拟真实使用场景50个用户同时登录操作并发跑查询和导出记录服务器CPU、内存占用以及每个请求的平均响应时间。第二周做部署测试放到反向代理后面用正式域名访问验证会话保持和超时配置。试做结束后用三组数据决定方向最大并发在线数、单次操作平均响应时间、新需求的平均交付周期。如果并发在线数稳定在300人以上且响应在可接受范围说明Unigui能支撑你的核心业务体量。如果50个用户就让服务器吃紧说明这个模型在你的硬件条件下行不通别硬扛。Unigui真正适合的是团队里没有专职前端、业务逻辑复杂重、界面交互要求中等的内部管理系统。快速交付迭代的价值会明显盖过性能上的妥协。不适合的场景也很清晰面向公众的C端产品、动画和自由布局要求很高的门户网站、以及预期日活过万的高并发业务。我在一次改造项目里吃过亏。某个业务系统初期为了快速上线选了Unigui前两个版本交付确实快但当业务要求引入大量地图组件和自定义复杂交互时服务器端渲染模型反而成了限制前端方案的改造成本远高于一开始就使用前后端分离。这个教训让我养成了一个习惯在选型阶段先做最小验证把已知的技术需求列清楚再决定方案走向。希望这篇笔记能帮你少走一些弯路。Unigui适合的场景里它确实是非常值得参考学习的开源框架但前提是你先确认自己走在适合它的那条路上。本文还有配套的精品资源点击获取