编码

编码是前端编码工程师、应用服务（C# 或 Java）编码工程师、数据库编码工程师使用的对应用或模块编写和提交源代码的页面。通过该页面提交的源代码会被压缩保存在服务器上。随后（多人）人工编写的代码和自动生成的代码由 Pittypat 自动合并输出为完整的 VS 解决方案或 Maven 工程。

Pittypat 允许开发人员直接在浏览器中编写相关的代码，也可以事先在本地 IDE 中编写源代码，通过浏览器粘贴提交到服务器。

在输出应用或模块、功能、对象时，如果尚未提交任何源代码，那么 Pittypat 会编写默认的源代码，如果已经提交了源代码，Pittypat 将输出开发者提交的源代码。因此在输出的解决方案中，源代码已经是开发者提交后的源代码，Pittypat 会自动合并人工提交的代码和自动生成的代码，不再需要生成发布人员再通过其他途径（比如邮件、QQ）从编码人员那里收集源代码并合并到解决方案中。

编码人员在编码时不应该修改声明性的代码，比如类的声明、函数的声明、存储过程的声明等代码，这些代码都是由 Pittypat 根据设计自动创建和维护的。如果编码人员认为声明不合理，比如缺少参数，或者参数类型不合理等，应该反馈给设计师，由设计师修订设计。

当需求等发生变更后，设计师可能会重新调整设计，并重新输出代码。如果此前编码工程师已经提交了源代码，Pittypat 会在输出的代码中使用人工编写的代码，而不是使用自动生成的代码。也就是说：

Pittypat 在输出代码时，不会覆盖已经写好并提交的人工代码。

源代码组织
Pittypat 允许在单个浏览器页面中编写 HTML、CSS、JS、Java、C# 或 SQL 代码。

根据安排工作时编码类别和模块的不同，不同开发者所看到的源代码资源管理器的结构是不同的。开发者仅能查看和编写安排给自己的工作任务对应的模块的代码。
1. Android AppShell
  
  Pittypat 实验性地为 Android 提供了一个 AppShell（下载 PittypatAppShell for Android Studio），这是一个在 Android 上对单个 WebView 的封装，开发者可以利用该 AppShell 实现一个原生应用，用于访问 Pittypat 应用的站点。
2. C#
  C#（文件扩展名 .cs）分为两个部分。一个是目标应用的业务代码，包括实体类和 Api 代码。另外一个是开源的 Pittypat 核心库代码。
  
  C# 代码组织
  - 应用业务代码
    
    位于 cs/com.{开发者代码}.{应用标识符}/{模块标识符} 目录下。
    
    Api.cs 文件包含了模块中所有功能的 Api 函数的定义和实现。由于 Pittypat 仅仅允许修改功能方法体的代码，因此 Api.cs 还可以继续展开，以便开发者按每一个功能编写和保存源代码。
    
    Args 目录中是模块中功能实体类的源代码文件列表，这些文件都不需要人工修改。
    
    Data 目录中是模块中对象实体类的源代码文件列表，这些文件都不需要人工修改。
  - Pittypat 核心库代码
    
    核心库源代码和基础功能的源代码都使用 BSD 协议开源。
    
    在浏览器中，仅仅允许开发者查看这些源代码，而不能修改。如果开发者需要修改这些源代码，应该在本地 IDE 中修改。
3. Java
  Java（文件扩展名 .java）分为两个部分。一个是目标应用的业务代码，包括实体类和 Api 代码。另外一个是开源的 Pittypat 核心库代码。
  
  Java 代码组织
  - 应用业务代码
    
    位于 java/com.{开发者代码}.{应用标识符}/{模块标识符} 目录下。
    
    Api.java 文件包含了模块中所有功能的 Api 函数的定义和实现。由于 Pittypat 仅仅允许修改功能方法体的代码，因此 Api.java 还可以继续展开，以便开发者按每一个功能编写和保存源代码。
    
    args 目录中是模块中功能实体类的源代码文件列表，这些文件都不需要人工修改。
    
    data 目录中是模块中对象实体类的源代码文件列表，这些文件都不需要人工修改。
  - Pittypat 核心库代码
    
    核心库源代码和基础功能的源代码都使用 BSD 协议开源。
    
    在浏览器中，仅仅允许开发者查看这些源代码，而不能修改。如果开发者需要修改这些源代码，应该在本地 IDE 中修改。
4. SQL
  SQL 代码文件位于 sql/com.{开发者代码}.{应用标识符}/{数据库类型} 目录下。数据库类型包括：mysql、sqlserver、oracle、db2 和 pgsql（PostgreSQL）。
  
  在不同数据库平台之间相互移植时，为了减少 SQL 代码的修改工作量，Pittypat 对所有的数据库对象标识符总是使用 "（双引号）引用标识符，对于默认不支持双引号的数据库需要事先调整为支持双引号，比如 MySQL 中需要启用 ANSI_QUOTES。
  
  SQL 代码组织
  
  Pittypat 为每一种数据库中的 .sql 文件名称前缀一个数字，表示它们的执行顺序。
  - 1_tables.sql
    
    包含了目标应用中所有数据库表的 SQL 代码。这些代码都不需要人工修改。开发者可以继续展开单独查看某一个表的代码。
  - 2_global.sql
    
    包含了目标应用数据库使用的公共的函数、视图或存储过程等的定义。该文件可能需要人工编写。默认的，Pittypat 提供了一组基础函数或存储过程，分别参见 MySQL 参考、SQL SERVER 参考和 ORACLE 参考。
  - 3_init.sql
    
    包含了用于初始化目标应用数据库的 SQL 代码。该文件可能需要人工调整。默认的，Pittypat 创建了目标应用在 waln_authority 中注册应用和模块列表的代码，如果不使用 waln_authority，这些初始化代码可以不要。
  - 4_views.sql
    
    包含了目标应用中所有对象视图的 SQL 代码。视图代码可能需要人工修改。开发者可以继续展开单独查看或修改某一个视图的代码。
  - 5_procedures.sql
    
    包含了目标应用中所有功能存储过程的 SQL 代码。存储过程代码可能需要人工修改。开发者可以继续展开单独查看或修改某一个存储过程的代码。
5. Web
  Web 前端代码包含 HTML、CSS 和 JS。
  
  Web 代码组织
  - web/css/pittypat.css
    
    定义 Pittypat 通用页面的样式表。不需要开发者修改。
  - web/js/pittypat.js
    
    包含了 long.js，以及 Pittypat 自定义的基础代码。不需要开发者修改。请参见 pittypat.js 参考。
  - web/index.html
    
    系统首页的 HTML。需要开发者修改。如果当前应用将融入其他应用站点中，可以不提供此页面。
  - web/index.js
    
    系统首页的 JS。需要开发者修改。如果当前应用将融入其他应用站点中，可以不提供此代码。
  - app.css
    
    位于 com.{开发者代码}.{应用标识符} 目录下，定义目标应用使用的公共的样式表。可能需要开发者修改。
  - app.js
    
    位于 com.{开发者代码}.{应用标识符} 目录下，定义目标应用使用的公共的 JS 代码。可能需要开发者修改。
  - _api.js
    
    位于 com.{开发者代码}.{应用标识符}/{模块标识符} 目录下，定义目标模块访问远程服务器使用 API。可能需要开发者修改，通常仅需要调整数据的客户端验证代码部分。
  - {功能标识符}.html
    
    位于 com.{开发者代码}.{应用标识符}/{模块标识符} 目录下，定义了目标功能对应的 HTML 代码。可能需要开发者修改。
  - {功能标识符}.js
    
    位于 com.{开发者代码}.{应用标识符}/{模块标识符} 目录下，定义了目标功能的前端交互 JS 代码。可能需要开发者修改。
  - 帮助页面
    
    位于 com.{开发者代码}.{应用标识符}/{模块标识符}/help 目录下，定义了目标模块帮助页面的 HTML 代码。可能需要开发者修改。
    
    此文件没有显示在编码页面的资源管理器中，未来可能需要专人编写帮助手册。在输出的 IDE 工程中可以编辑修改帮助页面。

人工编码量

根据我们的研究和实践，总代码量、自动代码量、人工代码量比例关系如下：

类别	代码	人工比例
前端代码	首页	70%
	app.css	30%
	app.js	10%
	_api.js	10%
	功能.html	54%
	功能.js	67%
C#/Java	对象实体类
	功能实体类
	功能 Api	11%
SQL	tables.sql
	global.sql	30%
	init.sql	30%
	views.sql	7%
	procedures.sql	63%
合计		24%

表

在 Pittypat 中，数据库表的源代码不需要人工编写，会由 Pittypat 自动根据开发者选择的数据库平台类型输出合适的 SQL 代码。

Pittypat 为数据库表输出的源代码不是简单的 create table，而是会事先检查表、列、索引是否已经存在，然后根据判断结果决定是要添加、更新还是删除。这种方式有利于在应用已经发布到生产环境中后，在不破坏现有数据的情况下再次更新数据库表的结构。

以下是 Pittypat 为 MySQL 创建的一个数据库表的源代码示例：
/* * # 数据库表 - MySql: * Books - 图书 * * # 描述: * 表示一本已经登记入库的图书。 */ drop procedure if exists "_pittypat_replace_table"; delimiter // create procedure "_pittypat_replace_table"() begin if not "_pittypat_table_exists"('Books') then create table "Books" ( "PK" bigint not null auto_increment primary key, -- 主键 "Id" binary(16) not null, -- Id "Name" varchar(50) not null, -- 名称 "Author" varchar(50) not null, -- 作者 "PublicationDate" date not null -- 出版日期 ); -- 索引 U_Books_Id alter table "Books" add constraint unique index "U_Books_Id" ( "Id" asc ); else -- 列 Id if not "_pittypat_column_exists"('Books', 'Id') then alter table "Books" add column "Id" binary(16) not null after "PK"; else alter table "Books" modify column "Id" binary(16) not null after "PK"; end if; -- 列 Name if not "_pittypat_column_exists"('Books', 'Name') then alter table "Books" add column "Name" varchar(50) not null after "Id"; else alter table "Books" modify column "Name" varchar(50) not null after "Id"; end if; -- 列 Author if not "_pittypat_column_exists"('Books', 'Author') then alter table "Books" add column "Author" varchar(50) not null after "Name"; else alter table "Books" modify column "Author" varchar(50) not null after "Name"; end if; -- 列 PublicationDate if not "_pittypat_column_exists"('Books', 'PublicationDate') then alter table "Books" add column "PublicationDate" date not null after "Author"; else alter table "Books" modify column "PublicationDate" date not null after "Author"; end if; -- 删除索引 U_Books_Id if "_pittypat_index_exists"('Books', 'U_Books_Id') then alter table "Books" drop index "U_Books_Id"; end if; -- 创建索引 U_Books_Id alter table "Books" add constraint unique index "U_Books_Id" ( "Id" asc ); end if; end // delimiter ; call "_pittypat_replace_table"(); drop procedure "_pittypat_replace_table"; /* select "Id", -- Id "Name", -- 名称 "Author", -- 作者 "PublicationDate" -- 出版日期 from "waln_library"."Books" where "Id" = $id; insert into "waln_library"."Books" ( "Id", -- Id "Name", -- 名称 "Author", -- 作者 "PublicationDate" -- 出版日期 ) values ( $id, -- Id $name, -- 名称 $author, -- 作者 $publicationDate -- 出版日期 ); update "waln_library"."Books" set "Id" = $id, -- Id "Name" = $name, -- 名称 "Author" = $author, -- 作者 "PublicationDate" = $publicationDate -- 出版日期 where "Id" = $id; delete from "waln_library"."Books" where "Id" = $id; */
注释部分的 select、insert、update、delete 语句用于工程师在编码过程中复制使用，减少自己编码的工作量。
对象 UI JS
在 功能.js 文件中，Pittypat 为该功能引用的每一个数据对象创建一个 _ui 命名空间中的 JS 对象，其中包含了与该数据对象相关的所有的 DOM 操作。JS 源代码可能需要人工调整。

以下一个 js 源代码示例（Pittypat 默认创建的代码）：
/* * // 图书 * // 表示一种图书的相关信息。 * Book: * { * // Id * // 图书的 Id。 * id: {uuid?}, * * // 名称 * // 图书的名称。 * name: {string?}, * * // 作者 * // 图书的作者姓名。 * author: {string?}, * * // 出版日期 * // 图书的出版日期。 * publicationDate: {date?} * } */ _ui.book = { /* * 将指定的 Book 对象绑定到目标元素。 * * @param {any} args API 的 args 事件创建的参数。 * @param {Object} model 一个 Book 对象。 * @param {jQuery} $model 要绑定到的 DOM 元素。 */ bind: function (args, model, $model) { if (!$model || !$model.length) { // 没有提供要绑定到的元素 return $model; } if (!model) { // 没有提供要绑定的对象 // 名称: {string?} $model.find('.model-book-name').tv(''); // 作者: {string?} $model.find('.model-book-author').tv(''); // 出版日期: {date?} $model.find('.model-book-publication-date').tv(''); } else { // 名称: {string?} $model.find('.model-book-name').tv(model.name); // 作者: {string?} $model.find('.model-book-author').tv(model.author); // 出版日期: {date?} $model.find('.model-book-publication-date').tv($$.util.fmt.day(model.publicationDate)); } return $model; }, /* * Book 对象的 HTML。 */ get html() { return '' + '<article class="pt-model model-book pt-fields">' + ' <div class="pt-field">' + ' <label>' + ' <b>名称</b>' + ' <input type="text" class="pt-model-prop model-book-name" readonly autocomplete="off" />' + ' </label>' + ' </div>' + ' <div class="pt-field">' + ' <label>' + ' <b>作者</b>' + ' <input type="text" class="pt-model-prop model-book-author" readonly autocomplete="off" />' + ' </label>' + ' </div>' + ' <div class="pt-field">' + ' <label>' + ' <b>出版日期</b>' + ' <input type="text" class="pt-model-prop model-book-publication-date" readonly autocomplete="off" />' + ' </label>' + ' </div>' + '</article>'; }, /* * 将指定的 Book 对象显示在指定位置。 * * @param {any} args API 的 args 事件创建的参数。 * @param {Object} model 一个 Book 对象。 * @param {jQuery} $context 要显示对象的上下文。 */ show: function (args, model, $context) { if (!model && !args) { // 没有提供 Book 对象，也没有提供任何可用的参数 return null; } // 目标元素隶属的上下文 $context = $($context || $main); // 查找现有的元素 var $model = $context.find('#model-book-' + (model ? model.id : (typeof args === 'object' ? args.id : args))); if (!$model.length) { // 没有找到现有的元素，创建新的元素 $model = $(_ui.book.html).appendTo($context); } // 将对象属性绑定到目标元素 return _ui.book.bind(args, model, $model).mdcInit(); }, /* * Book 对象在列表中的 HTML。 */ get rowHtml() { return '' + '<article class="pt-row pt-model model-book">' + ' <hr />' + ' <header class="hover">' + ' <div class="pt-row-icon">' + ' <i class="material-icons">favorite_border</i>' + ' </div>' + ' <div class="pt-row-info">' + ' <div>' + ' <span class="pt-model-prop model-book-name"></span>' + ' </div>' + ' <div class="w-8 hidden-phone hidden-tablet theme-text-2">' + ' <span class="pt-model-prop model-book-author"></span>' + ' </div>' + ' <div class="w-8 hidden-phone hidden-tablet theme-text-2">' + ' <span class="pt-model-prop model-book-publication-date"></span>' + ' </div>' + ' </div>' + ' <div class="pt-row-more">' + ' <button data-target-menu="#list-model-book-menu" class="mdc-ripple-surface mdc-ripple-surface--primary" data-mdc-ripple-is-unbounded data-mdc-auto-init="MDCRipple">' + ' <i class="material-icons">more_vert</i>' + ' </button>' + ' <i class="material-icons">expand_more</i>' + ' </div>' + ' </header>' + ' <section></section>' + '</article>'; }, /* * 将指定的 Book 对象添加到指定 DOM 列表的指定位置。 * * @param {any} args API 的 args 事件创建的参数。 * @param {Object} model 一个 Book 对象。 * @param {Number} pos 插入位置，小于 0 将添加到最后。 * @param {jQuery} $list 要插入的 DOM 列表。 */ insert: function (args, model, pos, $list) { if (!model) { // 没有提供 Book 对象 return null; } if (!$list || !$list.length) { // 目标元素列表 $list = $('#list-books'); } if (!$$.util.is.int(pos)) { // 添加到列表最后 pos = -1; } var // 隶属于目标列表中的所有对象元素 $all = $list.find('.model-book'), // 新创建的元素 $model = $(_ui.book.rowHtml); if (pos >= 0 && pos < $all.length) { // 插入到目标位置之前 $model.insertBefore($all.eq(pos)); } else { // 添加到列表最后 $model.appendTo($list); } // 将对象属性更新到目标元素 return _ui.book .update(args, model, $model, $list) .mdcInit(); }, /* * 将指定的 Book 对象数组添加到指定 DOM 列表的指定位置。 * * @param {any} args API 的 args 事件创建的参数。 * @param {Object} models 一个 Book 对象的数组。 * @param {Number} pos 插入位置，非数字将清空现有列表，小于 0 将添加到最后。 * @param {jQuery} $list 要插入的 DOM 列表。 */ insertAll: function (args, models, pos, $list) { if (!$list || !$list.length) { // 目标元素列表 $list = $('#list-books'); } if (args && args.pageIndex && Long.fromValue(args.pageIndex).eq(1)) { // 清空现有列表 $list.empty(); // 添加到列表最后 pos = -1; } if (models && models.length) { if (pos <= 0) { // 添加到最前或最后 models.each(function (model) { _ui.book.insert(args, model, pos, $list); }); } else { // 添加到指定位置 models.each(function (model, i) { _ui.book.insert(args, model, pos + i, $list); }); } } return $list; }, /* * 将指定的 Book 对象更新到现有的 DOM。 * * @param {any} args API 的 args 事件创建的参数。 * @param {Object} model 一个 Book 对象。 * @param {jQuery} $model 现有的 DOM。 * @param {jQuery} $list 隶属的 DOM 列表。 */ update: function (args, model, $model, $list) { if (!$list || !$list.length) { // 目标元素列表 $list = $('#list-books'); } if (!$model || !$model.length) { // 没有提供 $model 时根据 model 或 args 查找目标元素 $model = $list.find('#model-book-' + (model ? model.id : (typeof args === 'object' ? args.id : args))); } if (model && $model.length) { var $header = $model .attr('id', 'model-book-' + model.id) .data('model', model) .children('header'); // 绑定到 $header _ui.book.bind(args, model, $header); } return $model; }, /* * 将指定的 Book 对象对应的 DOM 元素从列表中移除。 * * @param {any} args API 的 args 事件创建的参数。 * @param {Object} model 一个 Book 对象。 * @param {jQuery} $list 要从中移除元素的 DOM 列表。 */ remove: function (args, model, $list) { if (!$list || !$list.length) { // 目标元素列表 $list = $('#list-books'); } $list.find('#model-book-' + (typeof args === 'object' ? args.id : args)).remove(); }, /* * 为 Book 对象分页列表更新页码信息。 * * @param {any} args API 的 args 事件创建的参数。 * @param {Number} total 符合条件的记录总数目。 * @param {Number} rows 当前加载的记录数目。 * @param {jQuery} $context 分页上下文。 */ paging: function (args, total, rows, $context) { // 当前分页上下文 $context = $($context || $main.find('.pt-paging')); var // 已经加载的所有行数显示元素 $loaded = $context.find('.pt-loaded-rows'), // 已经加载的总行数 loaded = Long.fromValue(rows), // 符合条件的总行数显示元素 $total = $context.find('.pt-total-rows'), // 加载更多按钮 $more = $context.find('.pt-more-rows'), // 当前页码 pageIndex = Long.fromValue(args.pageIndex || 1); // 符合条件总行数转换为 Long total = Long.fromValue(total); if (pageIndex.gt(1)) { // 当前加载的不是第一页，已加载总行数为现有行数加上新行数 loaded = loaded.add($loaded.tv()); } // 更新显示 $loaded.tv(loaded); $total.tv(total); // 是否还有更多 $more.css('display', loaded.gte(total) ? 'none' : 'flex'); return $context; }, /* * 为 Book 对象分页列表更新页码信息。 * * @param {Number} rows 发生改变的记录数目，如果增加一行为 1，如果是减少一行为 -1。 * @param {jQuery} $context 分页上下文。 */ rowsChanged: function (rows, $context) { // 当前分页上下文 $context = $($context || $main.find('.pt-paging')); var // 已经加载的所有行数显示元素 $loaded = $context.find('.pt-loaded-rows'), // 已经加载的总行数 loaded = Long.fromValue($loaded.tv()), // 符合条件的总行数显示元素 $total = $context.find('.pt-total-rows'), // // 符合条件总行数转换为 Long total = Long.fromValue($total.tv()), // 加载更多按钮 $more = $context.find('.pt-more-rows'); // 修改行数 loaded = loaded.add(rows); total = total.add(rows); // 更新显示 $loaded.tv(loaded); $total.tv(total); // 是否还有更多 $more.css('display', loaded.gte(total) ? 'none' : 'flex'); return $context; } };
1. bind()
  将指定的对象绑定到目标元素。
  
  语法
  _ui.obj.bind(args, model, $model)
  
  args
  
  进行服务器请求时传入的参数。
  
  model
  
  要绑定的数据对象实例。
  
  $model
  
  要绑定到的 DOM 元素。
  
  返回值
  
  $model，也就是要绑定到的 DOM 元素。
  此函数通常不负责绑定目标元素的结构、样式等，仅仅是将对象属性按要求的格式显示在对应位置上，内部不会创建新的对象 DOM 元素。$$.util.fmt 命名空间提供一组支持不同数据类型的格式化方法。
2. html
  这是一个属性的 get 方法，返回单个数据对象以表单方式显示时使用的 DOM 结构。
  
  语法
  _ui.obj.html
  
  返回值
  
  字符串格式的 HTML 片段。
3. show()
  根据 html 属性创建一个新的对象 DOM 元素，将新元素添加到目标上下文中，并使用 bind 绑定新元素。
  
  语法
  _ui.obj.show(args, model, $context)
  
  args
  
  进行服务器请求时传入的参数。
  
  model
  
  要绑定的数据对象实例。
  
  $context
  
  新创建的对象对应的 DOM 元素所处的上下文。
  
  返回值
  
  新创建的对象对应的 DOM 元素。
4. rowHtml
  这是一个属性的 get 方法，返回单个数据对象以列表行方式显示时使用的 DOM 结构。
  
  语法
  _ui.obj.rowHtml
  
  返回值
  
  字符串格式的 HTML 片段。
5. insert()
  为指定的数据对象基于 rowHtml 创建一个新的 DOM 元素，并将新元素添加到指定列表的指定位置。
  
  通常创建或插入（INSERT）一条数据后执行该函数，以便将新插入的数据对象显示在列表中。
  
  语法
  _ui.obj.insert(args, model, pos, $list)
  
  args
  
  进行服务器请求时传入的参数。
  
  model
  
  要添加到列表中的数据对象实例。
  
  pos
  
  数据对象对应的 DOM 元素在列表中的插入位置。如果为 0，添加到列表最前面。如果小于 0，则添加到列表最后面。
  
  $list
  
  数据对象对应的 DOM 元素要添加到的列表。
  
  返回值
  
  新创建的对象对应的 DOM 元素。
  示例
  
  _api.create // 为请求准备参数 .on('args', function(e) { e.args = { // 名称: {string(50)?} name: $('#create-name').tv(), // 作者: {string(50)?} author: $('#create-author').tv(), // 出版日期: {date?} publicationDate: $('#create-publication-date').tv() }; }) // 在提交前执行，可以设置 e.cancel 取消请求 .on('before', function(e) { // 显示 loading 动画 $$.ui.msg = '...'; }) // 请求成功后执行 .on('success', function(e) { // 服务器返回了一个 Book? _ui.book.insert(e.args, e.result, 0); }) // 取消请求或请求成功后执行 .on('load', function() { // 隐藏 loading 动画 $$.ui.msg = ''; });
6. insertAll()
  为一组数据对象基于 rowHtml 创建一组新的 DOM 元素，并将所有新元素添加到指定列表的指定位置。
  
  通常在查询（SELECT）到一组数据对象集合后执行该函数，以便将查询到的数据对象显示列表中。
  
  语法
  _ui.obj.insertAll(args, models, pos, $list)
  
  args
  
  进行服务器请求时传入的参数。
  
  models
  
  要添加到列表中的数据对象实例的数组。
  
  pos
  
  数据对象对应的 DOM 元素在列表中的插入位置。如果为 0，添加到列表最前面。如果小于 0，则添加到列表最后面。
  
  如果 pos 为 0，最终显示的顺序会与数组中元素的顺序相反。
  
  $list
  
  数据对象对应的 DOM 元素要添加到的列表。
  
  返回值
  
  $list 本身。
  示例
  
  _api.list // 为请求准备参数 .on('args', function(e) { e.args = { // 页码: {int64?} pageIndex: $('#list-page-index').tv(), // 页面尺寸: {int64?} pageSize: $('#list-page-size').tv(), // 排序名称: {string(30)?} orderName: $('#list-order-name').tv(), // 排序方向: {string(4)?} orderDirection: $('#list-order-direction').tv(), // 名称: {string(50)?} name: $('#list-name').tv(), // 作者: {string(50)?} author: $('#list-author').tv() }; }) // 在提交前执行，可以设置 e.cancel 取消请求 .on('before', function(e) { // 显示 loading 动画 $$.ui.msg = '...'; }) // 请求成功后执行 .on('success', function(e) { // 服务器返回了多个值 // 图书列表: Book[]? _ui.book.insertAll(e.args, e.result.books); }) // 取消请求或请求成功后执行 .on('load', function() { // 隐藏 loading 动画 $$.ui.msg = ''; });
7. update()
  将指定的数据对象更新到现有的 DOM 元素上。默认使用 bind 进行数据绑定。
  
  通常在更新（UPDATE）一条数据后执行该函数，以便更新数据对象的显示列表。
  
  语法
  _ui.obj.update(args, model, $model, $list)
  
  args
  
  进行服务器请求时传入的参数。
  
  model
  
  要更新的数据对象实例。
  
  $model
  
  现有的 DOM 元素。
  
  $list
  
  DOM 元素所处的集合。
  
  返回值
  
  $model 本身。
  示例
  
  _api.edit // 为请求准备参数 .on('args', function(e) { e.args = { // Id: {uuid} id: $('#edit-id').tv(), // 名称: {string(50)?} name: $('#edit-name').tv(), // 作者: {string(50)?} author: $('#edit-author').tv(), // 出版日期: {date?} publicationDate: $('#edit-publication-date').tv() }; }) // 在提交前执行，可以设置 e.cancel 取消请求 .on('before', function(e) { // 显示 loading 动画 $$.ui.msg = '...'; }) // 请求成功后执行 .on('success', function(e) { // 服务器返回了一个 Book? _ui.book.update(e.args, e.result, $('model-book-' + e.args.id)); }) // 取消请求或请求成功后执行 .on('load', function() { // 隐藏 loading 动画 $$.ui.msg = ''; });
8. remove()
  将指定参数或数据对象对应的 DOM 元素从列表中移除。
  
  通常在删除（INSERT）一条数据后执行该函数，以便更新数据对象的显示列表。
  
  语法
  _ui.obj.remove(args, model, $list)
  
  args
  
  进行服务器请求时传入的参数。
  
  model
  
  要从列表中移除的 DOM 元素对应的数据对象。
  
  $list
  
  DOM 元素所处的集合。
  示例
  
  _api.delete // 为请求准备参数 .on('args', function(e) { e.args = $('#delete-id').tv(); }) // 在提交前执行，可以设置 e.cancel 取消请求 .on('before', function(e) { // 显示 loading 动画 $$.ui.msg = '...'; }) // 请求成功后执行 .on('success', function(e) { // 服务器没有返回任何值 _ui.book.remove(e.args); }) // 取消请求或请求成功后执行 .on('load', function() { // 隐藏 loading 动画 $$.ui.msg = ''; });
9. paging()
  为数据对象的分页列表更新分页信息。
  
  通常与 insertAll 一起使用。
  
  语法
  _ui.obj.paging(args, total, rows, $context)
  
  args
  
  进行服务器请求时传入的参数。
  
  total
  
  复合条件的记录总数，用于计算需要的总页码数。
  
  rows
  
  当前加载的记录总数，通常是当前分页上的记录数目。
  
  $context
  
  分页信息元素所处的上下文。
  示例
  
  _api.list // 为请求准备参数 .on('args', function(e) { e.args = { // 页码: {int64?} pageIndex: $('#list-page-index').tv(), // 页面尺寸: {int64?} pageSize: $('#list-page-size').tv(), // 排序名称: {string(30)?} orderName: $('#list-order-name').tv(), // 排序方向: {string(4)?} orderDirection: $('#list-order-direction').tv(), // 名称: {string(50)?} name: $('#list-name').tv(), // 作者: {string(50)?} author: $('#list-author').tv() }; }) // 在提交前执行，可以设置 e.cancel 取消请求 .on('before', function(e) { // 显示 loading 动画 $$.ui.msg = '...'; }) // 请求成功后执行 .on('success', function(e) { // 服务器返回了多个值 // 总行数: int64? _ui.book.paging(e.args, e.result.totalRows, e.result.books.length); // 图书列表: Book[]? _ui.book.insertAll(e.args, e.result.books); }) // 取消请求或请求成功后执行 .on('load', function() { // 隐藏 loading 动画 $$.ui.msg = ''; });
10. rowsChanged()
  当添加一条或多条新数据，或者删除一条或多条数据时，用于更新分页信息。
  
  语法
  _ui.obj.rowsChanged(rows, $context)
  
  rows
  
  大于 0 表示新添加的数据行数，小于 0 表示删除的数据行数。
  
  $context
  
  分页信息元素所处的上下文。
  示例
  
  _api.delete // 为请求准备参数 .on('args', function(e) { e.args = $('#delete-id').tv(); }) // 在提交前执行，可以设置 e.cancel 取消请求 .on('before', function(e) { // 显示 loading 动画 $$.ui.msg = '...'; }) // 请求成功后执行 .on('success', function(e) { // 服务器没有返回任何值 _ui.book.remove(e.args); // 更新页码信息 _ui.book.rowsChanged(-1); }) // 取消请求或请求成功后执行 .on('load', function() { // 隐藏 loading 动画 $$.ui.msg = ''; });
对象实体类

Pittypat 为每一个数据对象在 C# 或 Java 中创建一个实体类。对象实体类的代码不需要人工调整。

以下是一个在 C# 中的示例（Pittypat 默认创建的代码）：
/*! * # 数据实体类: * Book - 图书 * * # 描述: * 表示一种图书的相关信息。 * * Copyright (c), 上海沃恩信息科技有限公司. * All rights reserved. */ using Pittypat; namespace Waln.Library.Storage.Data { /// <summary> /// 图书。 /// </summary> /// <remarks> /// 表示一种图书的相关信息。 /// </remarks> public sealed class Book : global::Pittypat.DataModel { #region 构造函数 /// <summary> /// 初始化 Book 类的一个新实例。 /// </summary> public Book() { // Id this.Id = null; // 名称 this.Name = null; // 作者 this.Author = null; // 出版日期 this.PublicationDate = null; } #endregion #region 属性 /// <summary> /// 获取或者设置Id。 /// </summary> /// <remarks> /// 图书的 Id。 /// </remarks> public @uuid? Id { get; set; } /// <summary> /// 获取或者设置名称。 /// </summary> /// <remarks> /// 图书的名称。 /// </remarks> public @string? Name { get; set; } /// <summary> /// 获取或者设置作者。 /// </summary> /// <remarks> /// 图书的作者姓名。 /// </remarks> public @string? Author { get; set; } /// <summary> /// 获取或者设置出版日期。 /// </summary> /// <remarks> /// 图书的出版日期。 /// </remarks> public @date? PublicationDate { get; set; } #endregion #region 方法 /// <summary> /// 从一个 IDataReader 中读取此对象。 /// </summary> /// <param name="reader">包含对象数据的 IDataReader 对象。</param> /// <exception cref="global::System.ArgumentNullException">reader 是 null。</exception> public override void Read(global::System.Data.IDataReader reader) { if (reader == null) { throw new global::System.ArgumentNullException("reader"); } // Id this.Id = reader.GetValue<@uuid>("Id", defaultValue: this.Id); // 名称 this.Name = reader.GetValue<@string>("Name", defaultValue: this.Name); // 作者 this.Author = reader.GetValue<@string>("Author", defaultValue: this.Author); // 出版日期 this.PublicationDate = reader.GetValue<@date>("PublicationDate", defaultValue: this.PublicationDate); } /// <summary> /// 将当前对象作为 JSON 字符串写入指定的文本流。 /// </summary> /// <param name="writer">目标文本流。</param> /// <exception cref="global::System.ArgumentNullException">writer 是 null。</exception> public override void Write(global::System.IO.TextWriter writer) { if (writer == null) { throw new global::System.ArgumentNullException("writer"); } writer.Write('{'); // Id writer.Write("\"id\":"); this.Id.Write(writer); writer.Write(','); // 名称 writer.Write("\"name\":"); this.Name.Write(writer); writer.Write(','); // 作者 writer.Write("\"author\":"); this.Author.Write(writer); writer.Write(','); // 出版日期 writer.Write("\"publicationDate\":"); this.PublicationDate.Write(writer); writer.Write('}'); } #endregion } }
以下是一个在 Java 中的示例（Pittypat 默认创建的代码）：
/* * # 数据实体类: * Book - 图书 * * # 描述: * 表示一种图书的相关信息。 * * Copyright (c), 上海沃恩信息科技有限公司. * All rights reserved. */ package com.waln.library.storage.data; /** * 图书。 * <p> * 表示一种图书的相关信息。 */ public final class Book extends pittypat.DataModel { /** * Id。 * <p> * 图书的 Id。 */ public java.util.UUID id; /** * 名称。 * <p> * 图书的名称。 */ public String name; /** * 作者。 * <p> * 图书的作者姓名。 */ public String author; /** * 出版日期。 * <p> * 图书的出版日期。 */ public java.time.LocalDate publicationDate; /** * 初始化 Book 类的一个新实例。 */ public Book() { super(); // Id this.id = null; // 名称 this.name = null; // 作者 this.author = null; // 出版日期 this.publicationDate = null; } /** * 从一个 DataReader 中读取此对象。 * * @param reader 包含对象数据的 DataReader 对象。 * * @see pittypat.DataModel#read(pittypat.data.DataReader) * @see pittypat.data.DataReader */ @Override public void read(pittypat.data.DataReader reader) { if (reader == null) { throw new IllegalArgumentException("reader is null。"); } // Id this.id = reader.getUuid("id", this.id); // 名称 this.name = reader.getString("name", this.name); // 作者 this.author = reader.getString("author", this.author); // 出版日期 this.publicationDate = reader.getDate("publicationDate", this.publicationDate); } /** * 将当前对象作为 JSON 字符串写入指定的文本流。 * * @param writer 目标文本流。 * * @throws java.io.IOException 数据写入时发生 IO 错误。 * * @see pittypat.DataModel#write(java.io.Writer) */ @Override public void write(java.io.Writer writer) throws java.io.IOException { if (writer == null) { throw new IllegalArgumentException("writer is null。"); } writer.write('{'); // Id writer.write("\"id\":"); pittypat.Json.write(writer, this.id); writer.write(','); // 名称 writer.write("\"name\":"); pittypat.Json.write(writer, this.name); writer.write(','); // 作者 writer.write("\"author\":"); pittypat.Json.write(writer, this.author); writer.write(','); // 出版日期 writer.write("\"publicationDate\":"); pittypat.Json.write(writer, this.publicationDate); writer.write('}'); } }
对象的实体类提供 read 和 writer 两个方法的实现。

read 用于从数据库查询到的 DataReader 中读取单个对象实例。在 .NET 中 IDataReader 是 ADO.NET 的一个基础接口，在 Java 中 DataReader 是 Pittypat 定义的一个基础对象。

write 用于将对象转换为 JSON 对象字符串，并写入指定的文本流，也就是实现对象的 JSON 序列化。在 .NET 中，Pittypat 重写了所有必要的基础类型（它们的标识符为 .NET 通用类型名称前缀 @ 符号，比如字符串为 @string），以便这些基础类型实现 IJson 接口，从而自己完成 JSON 序列化工作。在 Java 中，Pittypat 没有重写每一个基础类型，而是通过 pittypat.Json 帮助类实现基础类型的 JSON 序列化。
对象视图

Pittypat 为每一个对象创建一个数据库视图。视图的源代码可能需要人工调整，但是调整量非常少。

以下是 Pittypat 为 MySQL 创建的一个数据库视图的源代码示例（Pittypat 默认创建的代码）：
/* * # 对象视图 - MySql: * v_storage_book - 图书 * * # 描述: * 表示一本已经登记入库的图书。 */ create or replace view "waln_library"."v_storage_book" as select b."PK", -- 主键 b."Id", -- Id b."Name", -- 名称 b."Author", -- 作者 b."PublicationDate" -- 出版日期 from "waln_library"."books" as b;
在编写视图代码时，仅仅允许开发者编写 as 关键字之后的部分。Pittypat 会自动在最后添加一个 ;，不需要人工添加。如果人工添加了 ;，那么 Pittypat 将保留该符号，不再自动添加新的 ;。
功能 HTML

Pittypat 为每一个功能创建一个 html 文件。通常，除了模块第一个功能（入口功能）的 html 文件外，其他功能的 html 文件有可能是不需要的。

以下是一个示例（Pittypat 默认创建的代码）：
 <!DOCTYPE html> <html lang="zh-cmn-Hans"> <head> <title>图书列表 | 入库管理 | 图书管理系统</title> <meta charset="utf-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge, chrome=1" /> <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" /> <meta name="author" content="上海沃恩信息科技有限公司" />  <link rel="icon" type="image/png" href="../app.png" />  <link rel="stylesheet" href="../../../../mdc/material-components-web.min.css" /> <link rel="stylesheet" href="../../../../css/pittypat.min.css" /> <link rel="stylesheet" href="../app.css" />  <style> @media (min-width: 840px) { .pt-main { padding-top: 0; } } /* 分页信息 */ .pt-paging { margin: 16px 0; display: flex; flex-direction: column; justify-content: center; align-items: center; } /* 已加载以及总行数 */ .pt-loaded-rows, .pt-total-rows { color: rgba(0, 0, 0, 0.54); color: var(--mdc-theme-text-secondary-on-light, rgba(0, 0, 0, 0.54)); } .pt-loaded-rows::after { content: ' / '; } /* 搜索与加载按钮 */ .search-button, .pt-more-rows { background: none; border: none; padding: 0; margin: 0; display: flex; justify-content: center; align-items: center; } </style> </head> <body class="pt-nav-pinned">  <header>  <section class="pt-page-toolbar">  <button class="pt-nav-toggle mdc-ripple-surface" type="button" data-mdc-ripple-is-unbounded data-mdc-auto-init="MDCRipple"> <i class="material-icons">menu</i> </button>  <h1 class="pt-page-title">图书列表</h1>  <button data-target-dialog="#create-dialog" title="添加图书" class="mdc-ripple-surface" type="button" data-mdc-ripple-is-unbounded data-mdc-auto-init="MDCRipple"> <i class="material-icons">add</i> </button>  <button class="pt-nc-toggle mdc-ripple-surface" type="button" data-mdc-ripple-is-unbounded data-mdc-auto-init="MDCRipple"> <i class="material-icons">chat_bubble_outline</i>  <b></b> </button>  <button class="pt-page-menu-toggle mdc-ripple-surface" type="button" data-mdc-ripple-is-unbounded data-mdc-auto-init="MDCRipple"> <i class="material-icons">more_vert</i> </button>  <div class="pt-page-menu mdc-simple-menu mdc-simple-menu--open-from-top-right" tabindex="-1"> <div class="mdc-simple-menu__items mdc-list" role="menu" aria-hidden="true"> <a class="pt-page-refresh mdc-list-item" role="menuitem" tabindex="0"> <i class="material-icons mdc-list-item__start-detail">refresh</i> <span>刷新页面</span> </a> <div class="mdc-list-divider" role="separator"></div> <a class="mdc-list-item" role="menuitem" tabindex="0" href="help/index.html" target="_blank"> <i class="material-icons mdc-list-item__start-detail">help_outline</i> <span>查看帮助</span> </a> <div class="mdc-list-divider pt-page-menu-logout-divider" role="separator"></div> <a class="pt-page-menu-logout mdc-list-item" role="menuitem"> <i class="material-icons mdc-list-item__start-detail">power_settings_new</i> <span>退出</span> </a> </div> </div> </section> </header>  <main class="pt-main" role="main">  <div class="pt-fields">  <input type="hidden" id="list-page-index" value="1" />  <input type="hidden" id="list-page-size" value="20" />  <input type="hidden" id="list-order-name" value="" />  <input type="hidden" id="list-order-direction" value="asc" />  <div class="pt-field"> <label> <b>名称</b> <input id="list-name" type="text" maxlength="50" autocomplete="off" /> </label> </div>  <div class="pt-field"> <label> <b>作者</b> <input id="list-author" type="text" maxlength="50" autocomplete="off" /> </label> <button id="list-search" class="search-button mdc-ripple-surface mdc-ripple-surface--primary mdc-theme--primary" type="button" data-mdc-ripple-is-unbounded data-mdc-auto-init="MDCRipple"> <i class="material-icons">search</i> </button> </div> </div>  <article class="pt-row">  <header> <div class="pt-row-icon"></div> <div class="pt-row-info">  <div> <a class="pt-order-field" data-order-name="Name" data-order-direction="asc"> <label>名称</label> <i class="material-icons">arrow_drop_down</i> </a> </div>  <div class="w-8 hidden-phone hidden-tablet"> <a class="pt-order-field" data-order-name="Author" data-order-direction="asc"> <label>作者</label> <i class="material-icons">arrow_drop_down</i> </a> </div>  <div class="w-8 hidden-phone hidden-tablet"> <a class="pt-order-field" data-order-name="PublicationDate" data-order-direction="desc"> <label>出版日期</label> <i class="material-icons">arrow_drop_up</i> </a> </div> </div> <div class="pt-row-more"> <i></i> <i></i> </div> </header>  <section class="mdc-elevation--z1" id="list-books"></section> </article>  <div class="pt-paging"> <div>  <span class="pt-loaded-rows">0</span>  <span class="pt-total-rows">0</span> </div>  <button class="pt-more-rows mdc-ripple-surface mdc-ripple-surface--primary mdc-theme--primary" type="button" data-mdc-ripple-is-unbounded data-mdc-auto-init="MDCRipple"> <i class="material-icons">more_horiz</i> </button> </div> </main>  <div class="pt-menus-dialogs">  <div class="mdc-dialog" id="list-dialog">  <article class="mdc-dialog__surface">  <header class="mdc-dialog__header"> <h2 class="mdc-dialog__header__title" id="list-dialog-title"> 图书列表 </h2> </header>  <section class="mdc-dialog__body mdc-dialog__body--scrollable" id="list-dialog-body">  <div class="pt-fields">  <input type="hidden" id="list-page-index" value="1" />  <input type="hidden" id="list-page-size" value="20" />  <input type="hidden" id="list-order-name" value="" />  <input type="hidden" id="list-order-direction" value="asc" />  <div class="pt-field"> <label> <b>名称</b> <input id="list-name" type="text" maxlength="50" autocomplete="off" /> </label> </div>  <div class="pt-field"> <label> <b>作者</b> <input id="list-author" type="text" maxlength="50" autocomplete="off" /> </label> </div> </div> </section>  <footer class="mdc-dialog__footer">  <a class="pt-dialog-footer-help" href="help/index.html#list" target="_blank"> <i class="material-icons">help_outline</i> </a>  <div></div>  <button type="button" class="mdc-button mdc-dialog__footer__button" data-cancel>取消</button> <button type="button" class="mdc-button mdc-dialog__footer__button mdc-button--primary" data-ok>确定</button> </footer> </article>  <div class="mdc-dialog__backdrop"></div> </div>  <div class="mdc-dialog" id="create-dialog">  <article class="mdc-dialog__surface">  <header class="mdc-dialog__header"> <h2 class="mdc-dialog__header__title" id="create-dialog-title"> 添加图书 </h2> </header>  <section class="mdc-dialog__body mdc-dialog__body--scrollable" id="create-dialog-body">  <div class="pt-fields">  <div class="pt-field"> <label> <b>名称</b> <input id="create-name" type="text" maxlength="50" autocomplete="off" /> </label> </div>  <div class="pt-field"> <label> <b>作者</b> <input id="create-author" type="text" maxlength="50" autocomplete="off" /> </label> </div>  <div class="pt-field"> <label> <b>出版日期</b> <input id="create-publication-date" type="date" min="2000-01-01" max="2999-12-31" autocomplete="off" /> </label> </div> </div> </section>  <footer class="mdc-dialog__footer">  <a class="pt-dialog-footer-help" href="help/index.html#create" target="_blank"> <i class="material-icons">help_outline</i> </a>  <div></div>  <button type="button" class="mdc-button mdc-dialog__footer__button" data-cancel>取消</button> <button type="button" class="mdc-button mdc-dialog__footer__button mdc-button--primary" data-ok>确定</button> </footer> </article>  <div class="mdc-dialog__backdrop"></div> </div> </div>  <nav class="pt-nav"> <article class="pt-nav-panel"> <header>  <div class="pt-nav-toolbar">  <a class="mdc-ripple-surface" data-mdc-ripple-is-unbounded data-mdc-auto-init="MDCRipple" href="../../../../" title="返回首页"> <i class="material-icons">home</i> </a>  <a class="pt-nav-refresh mdc-ripple-surface" data-mdc-ripple-is-unbounded data-mdc-auto-init="MDCRipple" title="刷新导航"> <i class="material-icons">update</i> </a>  <a class="pt-nav-pin mdc-ripple-surface" data-mdc-ripple-is-unbounded data-mdc-auto-init="MDCRipple" title="取消固定导航"> <i class="material-icons">call_received</i> </a> </div>  <div class="pt-nav-userbar"> <a href="../../../waln/authority/profile/index.html">  <i class="material-icons">account_circle</i>  <b>未登录</b> </a> </div> </header>  <section></section> </article>  <div></div> </nav>  <aside class="pt-nc"> <article class="pt-nc-panel"> <header>  <a class="pt-nc-close mdc-ripple-surface" data-mdc-ripple-is-unbounded data-mdc-auto-init="MDCRipple" data-nc-close> <i class="material-icons">close</i> </a> <h1>通知中心</h1>  <a class="mdc-ripple-surface" data-mdc-ripple-is-unbounded data-mdc-auto-init="MDCRipple" href="../../../waln/notifying/inbox/list.html" title="打开收件箱"> <i class="material-icons">inbox</i> </a> </header>  <section></section> </article>  <div></div> </aside>   <script src="../../../../js/jquery.min.js"></script>  <script src="../../../../mdc/material-components-web.min.js"></script>  <script src="../../../../js/pittypat.min.js"></script>  <script src="../app.js"></script>  <script src="_api.js"></script>  <script src="list.js"></script> </body> </html>
功能 JS

Pittypat 为每一个功能在目标模块的 js 文件中创建一个 API 的 AJAX 或 Web Socket 调用。

以下是一个示例（Pittypat 默认创建的代码）：
/*! * # 功能 JS: * List - 图书列表 * * # 描述: * 功能 List 的用户交互实现，包括 DOM 操作和事件等。 * * Copyright (c), 上海沃恩信息科技有限公司. * All rights reserved. */ $(function () { 'use strict'; var // 模块的根命名空间 _mod = $$.namespace('waln.library.storage'), // 模块的 UI 命名空间 _ui = _mod.ui = _mod.ui || {}, // 模块的 API 命名空间 _api = _mod.api, // 主工作区 $main = $('.pt-main'); // DOM 定义 (function () { /* * // 图书 * // 表示一种图书的相关信息。 * Book: * { * // Id * // 图书的 Id。 * id: {uuid?}, * * // 名称 * // 图书的名称。 * name: {string?}, * * // 作者 * // 图书的作者姓名。 * author: {string?}, * * // 出版日期 * // 图书的出版日期。 * publicationDate: {date?} * } */ _ui.book = { /* * 将指定的 Book 对象绑定到目标元素。 * * @param {any} args API 的 args 事件创建的参数。 * @param {Object} model 一个 Book 对象。 * @param {jQuery} $model 要绑定到的 DOM 元素。 */ bind: function (args, model, $model) { if (!$model || !$model.length) { // 没有提供要绑定到的元素 return $model; } if (!model) { // 没有提供要绑定的对象 // 名称: {string?} $model.find('.model-book-name').tv(''); // 作者: {string?} $model.find('.model-book-author').tv(''); // 出版日期: {date?} $model.find('.model-book-publication-date').tv(''); } else { // 名称: {string?} $model.find('.model-book-name').tv(model.name); // 作者: {string?} $model.find('.model-book-author').tv(model.author); // 出版日期: {date?} $model.find('.model-book-publication-date').tv($$.util.fmt.day(model.publicationDate)); } return $model; }, /* * Book 对象的 HTML。 */ get html() { return '' + '<article class="pt-model model-book pt-fields">' + ' <div class="pt-field">' + ' <label>' + ' <b>名称</b>' + ' <input type="text" class="pt-model-prop model-book-name" readonly autocomplete="off" />' + ' </label>' + ' </div>' + ' <div class="pt-field">' + ' <label>' + ' <b>作者</b>' + ' <input type="text" class="pt-model-prop model-book-author" readonly autocomplete="off" />' + ' </label>' + ' </div>' + ' <div class="pt-field">' + ' <label>' + ' <b>出版日期</b>' + ' <input type="text" class="pt-model-prop model-book-publication-date" readonly autocomplete="off" />' + ' </label>' + ' </div>' + '</article>'; }, /* * 将指定的 Book 对象显示在指定位置。 * * @param {any} args API 的 args 事件创建的参数。 * @param {Object} model 一个 Book 对象。 * @param {jQuery} $context 要显示对象的上下文。 */ show: function (args, model, $context) { if (!model && !args) { // 没有提供 Book 对象，也没有提供任何可用的参数 return null; } // 目标元素隶属的上下文 $context = $($context || $main); // 查找现有的元素 var $model = $context.find('#model-book-' + (model ? model.id : (typeof args === 'object' ? args.id : args))); if (!$model.length) { // 没有找到现有的元素，创建新的元素 $model = $(_ui.book.html).appendTo($context); } // 将对象属性绑定到目标元素 return _ui.book.bind(args, model, $model).mdcInit(); }, /* * Book 对象在列表中的 HTML。 */ get rowHtml() { return '' + '<article class="pt-row pt-model model-book">' + ' <hr />' + ' <header class="hover">' + ' <div class="pt-row-icon">' + ' <i class="material-icons">favorite_border</i>' + ' </div>' + ' <div class="pt-row-info">' + ' <div>' + ' <span class="pt-model-prop model-book-name"></span>' + ' </div>' + ' <div class="w-8 hidden-phone hidden-tablet theme-text-2">' + ' <span class="pt-model-prop model-book-author"></span>' + ' </div>' + ' <div class="w-8 hidden-phone hidden-tablet theme-text-2">' + ' <span class="pt-model-prop model-book-publication-date"></span>' + ' </div>' + ' </div>' + ' <div class="pt-row-more">' + ' <button data-target-menu="#list-model-book-menu" class="mdc-ripple-surface mdc-ripple-surface--primary" data-mdc-ripple-is-unbounded data-mdc-auto-init="MDCRipple">' + ' <i class="material-icons">more_vert</i>' + ' </button>' + ' <i class="material-icons">expand_more</i>' + ' </div>' + ' </header>' + ' <section></section>' + '</article>'; }, /* * 将指定的 Book 对象添加到指定 DOM 列表的指定位置。 * * @param {any} args API 的 args 事件创建的参数。 * @param {Object} model 一个 Book 对象。 * @param {Number} pos 插入位置，小于 0 将添加到最后。 * @param {jQuery} $list 要插入的 DOM 列表。 */ insert: function (args, model, pos, $list) { if (!model) { // 没有提供 Book 对象 return null; } if (!$list || !$list.length) { // 目标元素列表 $list = $('#list-books'); } if (!$$.util.is.int(pos)) { // 添加到列表最后 pos = -1; } var // 隶属于目标列表中的所有对象元素 $all = $list.find('.model-book'), // 新创建的元素 $model = $(_ui.book.rowHtml); if (pos >= 0 && pos < $all.length) { // 插入到目标位置之前 $model.insertBefore($all.eq(pos)); } else { // 添加到列表最后 $model.appendTo($list); } // 将对象属性更新到目标元素 return _ui.book .update(args, model, $model, $list) .mdcInit(); }, /* * 将指定的 Book 对象数组添加到指定 DOM 列表的指定位置。 * * @param {any} args API 的 args 事件创建的参数。 * @param {Object} models 一个 Book 对象的数组。 * @param {Number} pos 插入位置，非数字将清空现有列表，小于 0 将添加到最后。 * @param {jQuery} $list 要插入的 DOM 列表。 */ insertAll: function (args, models, pos, $list) { if (!$list || !$list.length) { // 目标元素列表 $list = $('#list-books'); } if (args && args.pageIndex && Long.fromValue(args.pageIndex).eq(1)) { // 清空现有列表 $list.empty(); // 添加到列表最后 pos = -1; } if (models && models.length) { if (pos <= 0) { // 添加到最前或最后 models.each(function (model) { _ui.book.insert(args, model, pos, $list); }); } else { // 添加到指定位置 models.each(function (model, i) { _ui.book.insert(args, model, pos + i, $list); }); } } return $list; }, /* * 将指定的 Book 对象更新到现有的 DOM。 * * @param {any} args API 的 args 事件创建的参数。 * @param {Object} model 一个 Book 对象。 * @param {jQuery} $model 现有的 DOM。 * @param {jQuery} $list 隶属的 DOM 列表。 */ update: function (args, model, $model, $list) { if (!$list || !$list.length) { // 目标元素列表 $list = $('#list-books'); } if (!$model || !$model.length) { // 没有提供 $model 时根据 model 或 args 查找目标元素 $model = $list.find('#model-book-' + (model ? model.id : (typeof args === 'object' ? args.id : args))); } if (model && $model.length) { var $header = $model .attr('id', 'model-book-' + model.id) .data('model', model) .children('header'); // 绑定到 $header _ui.book.bind(args, model, $header); } return $model; }, /* * 将指定的 Book 对象对应的 DOM 元素从列表中移除。 * * @param {any} args API 的 args 事件创建的参数。 * @param {Object} model 一个 Book 对象。 * @param {jQuery} $list 要从中移除元素的 DOM 列表。 */ remove: function (args, model, $list) { if (!$list || !$list.length) { // 目标元素列表 $list = $('#list-books'); } $list.find('#model-book-' + (typeof args === 'object' ? args.id : args)).remove(); }, /* * 为 Book 对象分页列表更新页码信息。 * * @param {any} args API 的 args 事件创建的参数。 * @param {Number} total 符合条件的记录总数目。 * @param {Number} rows 当前加载的记录数目。 * @param {jQuery} $context 分页上下文。 */ paging: function (args, total, rows, $context) { // 当前分页上下文 $context = $($context || $main.find('.pt-paging')); var // 已经加载的所有行数显示元素 $loaded = $context.find('.pt-loaded-rows'), // 已经加载的总行数 loaded = Long.fromValue(rows), // 符合条件的总行数显示元素 $total = $context.find('.pt-total-rows'), // 加载更多按钮 $more = $context.find('.pt-more-rows'), // 当前页码 pageIndex = Long.fromValue(args.pageIndex || 1); // 符合条件总行数转换为 Long total = Long.fromValue(total); if (pageIndex.gt(1)) { // 当前加载的不是第一页，已加载总行数为现有行数加上新行数 loaded = loaded.add($loaded.tv()); } // 更新显示 $loaded.tv(loaded); $total.tv(total); // 是否还有更多 $more.css('display', loaded.gte(total) ? 'none' : 'flex'); return $context; }, /* * 为 Book 对象分页列表更新页码信息。 * * @param {Number} rows 发生改变的记录数目，如果增加一行为 1，如果是减少一行为 -1。 * @param {jQuery} $context 分页上下文。 */ rowsChanged: function (rows, $context) { // 当前分页上下文 $context = $($context || $main.find('.pt-paging')); var // 已经加载的所有行数显示元素 $loaded = $context.find('.pt-loaded-rows'), // 已经加载的总行数 loaded = Long.fromValue($loaded.tv()), // 符合条件的总行数显示元素 $total = $context.find('.pt-total-rows'), // // 符合条件总行数转换为 Long total = Long.fromValue($total.tv()), // 加载更多按钮 $more = $context.find('.pt-more-rows'); // 修改行数 loaded = loaded.add(rows); total = total.add(rows); // 更新显示 $loaded.tv(loaded); $total.tv(total); // 是否还有更多 $more.css('display', loaded.gte(total) ? 'none' : 'flex'); return $context; } }; })(); /* * 为登录用户注册一个处理函数。 * 由于没有为匿名用户注册处理函数，如果用户尚未登录，则会跳转到首页。 * * 详细帮助请参见： * https://www.pittypat.work/com/waln/pittypat/ref/help/pittypat.js.html#pittypat。 * * 参数 _ 的定义如下： * { * user: {Object}, // (只读)当前用户的用户信息 * app: {Object}, // (只读)当前应用的命名空间，如果无法定位，则为 null * mod: {Object}, // (只读)当前模块的命名空间，如果无法定位，则为 null * init: {Boolean}, // (只读)是否正在初始化页面 * first: {Boolean}, // (只读)是否首次执行 authorized * data: {any} // (读写)前述的 data 数据，或 data 函数返回的结果 * } */ $$(function (_) { if (_.init) { // 为 _api.list 注册事件 _api.list // 为请求准备参数 .on('args', function(e) { e.args = { // 页码: {int64?} pageIndex: $('#list-page-index').tv(), // 页面尺寸: {int64?} pageSize: $('#list-page-size').tv(), // 排序名称: {string(30)?} orderName: $('#list-order-name').tv(), // 排序方向: {string(4)?} orderDirection: $('#list-order-direction').tv(), // 名称: {string(50)?} name: $('#list-name').tv(), // 作者: {string(50)?} author: $('#list-author').tv() }; }) // 在提交前执行，可以设置 e.cancel 取消请求 .on('before', function(e) { // 显示 loading 动画 $$.ui.msg = '...'; }) // 请求成功后执行 .on('success', function(e) { // 服务器返回了多个值 // 总行数: int64? _ui.book.paging(e.args, e.result.totalRows, e.result.books.length); // 图书列表: Book[]? _ui.book.insertAll(e.args, e.result.books); }) // 取消请求或请求成功后执行 .on('load', function() { // 隐藏 loading 动画 $$.ui.msg = ''; }); // 为 _api.create 注册事件 _api.create // 为请求准备参数 .on('args', function(e) { e.args = { // 名称: {string(50)?} name: $('#create-name').tv(), // 作者: {string(50)?} author: $('#create-author').tv(), // 出版日期: {date?} publicationDate: $('#create-publication-date').tv() }; }) // 在提交前执行，可以设置 e.cancel 取消请求 .on('before', function(e) { // 显示 loading 动画 $$.ui.msg = '...'; }) // 请求成功后执行 .on('success', function(e) { // 服务器返回了一个 Book? _ui.book.insert(e.args, e.result, 0); // 增加一行 _ui.book.rowsChanged(1); // 重置页面或对话框 // 名称: {string(50)?} $('#create-name').tv(''); // 作者: {string(50)?} $('#create-author').tv(''); // 出版日期: {date?} $('#create-publication-date').tv(''); }) // 取消请求或请求成功后执行 .on('load', function() { // 隐藏 loading 动画 $$.ui.msg = ''; }); // 为添加图书对话框注册事件 $('#create-dialog') // 当对话框即将打开时 .on('opening', function (openingEvent) { var model = openingEvent.model; if (model) { // 对话框标题 $('#create-dialog-title').text('添加图书'); // 名称: {string(50)?} $('#create-name').tv(model.name); // 作者: {string(50)?} $('#create-author').tv(model.author); // 出版日期: {date?} $('#create-publication-date').tv($$.util.fmt.day(model.publicationDate, '-')); } }) // 当对话框打开后 .on('opened', function (openedEvent) { // 设置默认焦点 $('#create-name').focus(); }) // 当用户点击了确定按钮时 .on('ok', function (okEvent) { // 执行 API 请求 _api.create // 操作完成时关闭对话框 .one('load', function () { // 关闭对话框 okEvent.done = true; }) // 执行请求 (); }); // 排序 $('.pt-order-field').on('click', function (e) { // 阻止排序链接上的默认行为 e.preventDefault(); var // 点击的排序字段 $me = $(this), // 排序字段上定义的排序方向（不区分大小写） dir = ($me.attr('data-order-direction') || 'asc').toLowerCase(), // 排序字段上定义的排序名称（不区分大小写），如果没有提供，则按默认排序名称排序 name = ($me.attr('data-order-name') || '').toLowerCase(); // 反转排序方向 dir = dir === 'asc' ? 'desc' : 'asc'; // 设置排序方向指示图标 $me.attr('data-order-direction', dir) .children('.material-icons').text('arrow_drop_' + (dir === 'desc' ? 'up' : 'down')); // 设置排序条件 $('#list-order-name').val(name); $('#list-order-direction').val(dir); // 重置页码 $('#list-page-index').val(1); // 重新加载列表 _api.list(); }); // 搜索按钮 $('#list-search').on('click', function () { $('#list-page-index').val(1); _api.list(); }); // 加载更多 $('.pt-more-rows').on('click', function () { var $pi = $('#list-page-index'); $pi.val(parseInt($pi.val(), 10) + 1); _api.list(); }); // 初始化主工作区的 Material Design Components $main.mdcInit(); } // 模块入口： // 图书列表 _api.list(); }); });
功能实体类

Pittypat 为每一个功能创建一个实体类，该类包含了一个功能所有的参数的定义，每一个参数在类中对应一个属性，或者对应一对 get 和 set 方法。

以下是在 C# 中的一个示例（Pittypat 默认创建的代码）：
/*! * # 参数列表实体类: * Create - 添加图书 * * # 描述: * 添加一个新的图书。 * * Copyright (c), 上海沃恩信息科技有限公司. * All rights reserved. */ using Pittypat; namespace Waln.Library.Storage.Args { /// <summary> /// 功能添加图书的参数列表。 /// </summary> [global::Pittypat.Function(Transaction = true)] public sealed class Create : global::Pittypat.FunctionArgs { #region 构造函数 /// <summary> /// 初始化 Create 类的一个新实例。 /// </summary> public Create() { // 名称 this.Name = null; // 作者 this.Author = null; // 出版日期 this.PublicationDate = null; // 图书 this.Book = null; } #endregion #region 属性 /// <summary> /// 获取或者设置名称。 /// </summary> /// <remarks> /// 图书的名称。 /// </remarks> [global::Pittypat.Parameter(0, MaxLength = 50)] public @string? Name { get; set; } /// <summary> /// 获取或者设置作者。 /// </summary> /// <remarks> /// 图书的作者。 /// </remarks> [global::Pittypat.Parameter(1, MaxLength = 50)] public @string? Author { get; set; } /// <summary> /// 获取或者设置出版日期。 /// </summary> /// <remarks> /// 图书的出版日期。 /// </remarks> [global::Pittypat.Parameter(2)] public @date? PublicationDate { get; set; } /// <summary> /// 获取或者设置图书。 /// </summary> /// <remarks> /// 添加成功后的图书信息。 /// </remarks> [global::Pittypat.Parameter(3, Direction = global::Pittypat.ParameterDirection.Out)] public global::Waln.Library.Storage.Data.Book Book { get; set; } /// <summary> /// 获取或者设置指定名称的参数值。 /// </summary> /// <param name="name">参数名称，不区分大小写。</param> /// <returns>目标名称的参数值。如果参数不存在，则返回 null。</returns> /// <exception cref="global::System.ArgumentException">设置参数值时发现参数不存在。</exception> public override object this[string name] { get { if (string.IsNullOrEmpty(name)) { return null; } switch (name.ToLower()) { case "name": return this.Name; case "author": return this.Author; case "publicationdate": return this.PublicationDate; case "book": return this.Book; default: return null; } } set { if (string.IsNullOrEmpty(name)) { throw new global::System.ArgumentException("没有提供有效的参数名称。", "name"); } switch (name.ToLower()) { case "name": this.Name = (@string?)value; break; case "author": this.Author = (@string?)value; break; case "publicationdate": this.PublicationDate = (@date?)value; break; case "book": this.Book = (global::Waln.Library.Storage.Data.Book)value; break; default: throw new global::System.ArgumentException(name + " 不是 " + this.GetType().Name + " 的有效参数属性名称。", "name"); } } } #endregion #region 方法 /// <summary> /// 将当前对象作为 JSON 字符串写入指定的文本流。 /// </summary> /// <param name="writer">目标文本流。</param> /// <exception cref="global::System.ArgumentNullException">writer 是 null。</exception> public override void Write(global::System.IO.TextWriter writer) { if (writer == null) { throw new global::System.ArgumentNullException("writer"); } writer.Write('{'); // 名称 writer.Write("\"name\":"); this.Name.Write(writer); writer.Write(','); // 作者 writer.Write("\"author\":"); this.Author.Write(writer); writer.Write(','); // 出版日期 writer.Write("\"publicationDate\":"); this.PublicationDate.Write(writer); writer.Write(','); // 图书 writer.Write("\"book\":"); if (this.Book == null) { writer.Write("null"); } else { this.Book.Write(writer); } writer.Write('}'); } #endregion } }
以下是在 Java 中的一个示例（Pittypat 默认创建的代码）：
/* * # 参数列表实体类: * Create - 添加图书 * * # 描述: * 添加一种新的图书。 * * Copyright (c), 上海沃恩信息科技有限公司. * All rights reserved. */ package com.waln.library.storage.args; /** * 功能添加图书的参数列表。 */ @pittypat.FunctionAnnotation(transaction = true) public final class Create extends pittypat.FunctionArgs { /** * 当前用户 Id。 * <p> * 当前用户的用户 Id。 */ @pittypat.ParameterAnnotation(position = 0, role = pittypat.ParameterRole.USER_ID) public java.util.UUID userId; /** * 名称。 * <p> * 图书的名称。 */ @pittypat.ParameterAnnotation(position = 1, maxLength = 50) public String name; /** * 作者。 * <p> * 图书的作者姓名。 */ @pittypat.ParameterAnnotation(position = 2, maxLength = 50) public String author; /** * 出版日期。 * <p> * 图书的出版日期。 */ @pittypat.ParameterAnnotation(position = 3) public java.time.LocalDate publicationDate; /** * 新添加的图书。 * <p> * 新添加的图书信息。 */ @pittypat.ParameterAnnotation(position = 4, direction = pittypat.ParameterDirection.OUT) public com.waln.library.storage.data.Book book; /** * 初始化 Create 类的一个新实例。 */ public Create() { super(); // 当前用户 Id this.userId = null; // 名称 this.name = null; // 作者 this.author = null; // 出版日期 this.publicationDate = null; // 新添加的图书 this.book = null; } /** * 获取指定名称的参数值。 * * @param name 参数名称，不区分大小写。 * @return 指定名称的参数值。 */ @Override public Object getParameterValue(String name) { if (name == null || name.length() == 0) { return null; } switch (name.toLowerCase()) { case "userid": return this.userId; case "name": return this.name; case "author": return this.author; case "publicationdate": return this.publicationDate; case "book": return this.book; default: return null; } } /** * 设置指定名称的参数值。 * * @param name 参数名称，不区分大小写。 * @param value 参数值。 */ @Override public void setParameterValue(String name, Object value) { if (name == null || name.length() == 0) { throw new IllegalArgumentException("没有提供有效的参数名称。"); } switch (name.toLowerCase()) { case "userid": this.userId = (java.util.UUID) value; break; case "name": this.name = (String) value; break; case "author": this.author = (String) value; break; case "publicationdate": this.publicationDate = (java.time.LocalDate) value; break; case "book": this.book = (com.waln.library.storage.data.Book) value; break; default: throw new IllegalArgumentException(name + " 不是 " + this.getClass().getName() + " 的有效参数属性名称。"); } } /** * 将当前对象作为 JSON 字符串写入指定的文本流。 * * @param writer 目标文本流。 * * @throws java.io.IOException 数据写入时发生 IO 错误。 */ @Override public void write(java.io.Writer writer) throws java.io.IOException { if (writer == null) { throw new IllegalArgumentException("writer is null。"); } writer.write('{'); // 当前用户 Id writer.write("\"userId\":"); pittypat.Json.write(writer, this.userId); writer.write(','); // 名称 writer.write("\"name\":"); pittypat.Json.write(writer, this.name); writer.write(','); // 作者 writer.write("\"author\":"); pittypat.Json.write(writer, this.author); writer.write(','); // 出版日期 writer.write("\"publicationDate\":"); pittypat.Json.write(writer, this.publicationDate); writer.write(','); // 新添加的图书 writer.write("\"book\":"); pittypat.Json.write(writer, this.book); writer.write('}'); } }
C# 中索引器或者 Java 中 setParameterValue 和 getParameterValue 用于以字典的方式设置或获取对象的属性值。这种方式能够避免通过反射获取或设置属性值，提高效率。

write 方法用于将对象序列化为 JSON 字符串，并写入目标文本流。
功能 API

Pittypat 为每一个功能在模块类中创建一个方法。在 C# 中总是创建为异步方法。

以下是在 C# 中的一个示例（Pittypat 默认创建的代码）：
#region CreateAsync /// <summary> /// 添加一种新的图书。 /// </summary> /// <param name="model">功能模型对象，其中包含了功能的参数列表、执行状态以及相关消息。</param> /// <param name="progress">跟踪和汇报异步操作的进度。</param> /// <returns>操作成功返回新添加的图书，否则返回 null。</returns> public async global::System.Threading.Tasks.Task<global::Pittypat.IJson> CreateAsync( global::Pittypat.FunctionModel<Args.Create> model, global::Pittypat.IAsyncProgress progress) { // 执行数据操作 await this.DataService.Exec(model, progress); // 如果操作成功，返回新添加的图书 return model.Success ? model.Args.Book : null; } #endregion
以下是在 Java 中的一个示例（Pittypat 默认创建的代码）：
/** * 添加一种新的图书。 * * @param model 功能模型对象，其中包含了功能的参数列表、执行状态以及相关消息。 * @param progress 跟踪和汇报异步操作的进度。 * * @return pittypat.IJson 操作成功返回新添加的图书，否则返回 null。 */ public pittypat.IJson create( pittypat.FunctionModel<com.waln.library.storage.args.Create> model, pittypat.IAsyncProgress progress) { // 执行数据操作 this.getDataService().exec(model, progress); // 如果操作成功，返回新添加的图书 return model.isSuccess() ? model.getArgs().book : null; }
C# 中总是使用异步方法，目前 Java 不支持异步的方式执行功能方法。

model 参数提供了功能的参数列表、当前用户信息等，具体请参见 FunctionModel 类的定义。

progress 用于在操作过程中向客户端随时汇报操作的进度。目前只对 Web Socket 操作有效。具体请参见 IAsyncProgress 接口的定义。
功能存储过程
Pittypat 为每一个功能在目标数据库中创建一个存储过程或数据库函数。

以下是针对 MySQL 数据库的一个示例（Pittypat 默认创建的代码）：
/* * # 存储过程 - MySql: * p_storage_create - 添加图书 * * # 描述: * 添加一个新的图书。 */ drop procedure if exists "waln_library"."p_storage_create"; delimiter // create procedure "waln_library"."p_storage_create" ( in $name varchar(50), -- 名称 in $author varchar(50), -- 作者 in $publicationDate date, -- 出版日期 in $_context text, -- 当前环境变量参数 out $_success bool, -- 指示操作是否成功 out $_message text -- 操作中产生的消息 ) _proc_body: begin -- 主键 -- declare $pk bigint default null; -- Id -- declare $id binary(16) default null; -- 当前日期时间 -- declare $now datetime default current_timestamp; -- 默认指示操作失败 set $_success = false; set $_message = N''; -- 验证参数 $name (名称) if $name is null or $name = '' then set $_message = N'没有提供名称。'; leave _proc_body; end if; -- 验证参数 $author (作者) if $author is null or $author = '' then set $_message = N'没有提供作者。'; leave _proc_body; end if; -- 验证参数 $publicationDate (出版日期) if $publicationDate is null then set $_message = N'没有提供出版日期。'; leave _proc_body; end if; insert into "waln_library"."books" ( "Name", "Author", "PublicationDate" ) values ( $name, $author, $publicationDate ); -- 返回 Create.book：图书 select v.* from "waln_library"."v_storage_book" as v where v."col" = $col limit 1; -- 指示操作成功 set $_success = true; -- 记录操作日志 set @_log_id = null; call "waln_log"."log_op" ( null, -- 当前用户的 Id 2, -- 操作类型代码组合：1-查询、2-添加、4-更新、8-删除、16-其他 'waln_library.books', -- 相关数据库表的名称列表 'waln_library.p_storage_create', -- 存储过程名称 $_success, -- 指示操作是否成功 N'添加一个新的图书。', -- 详细的操作描述 $_context, -- 当前环境变量参数 @_log_id -- 日志消息的 Id ); end // delimiter ;
为了保障数据安全，应该总是在存储过程开始处对输入的所有参数进行合法性和有效性检查。

存储过程中的参数包括开发者定义的参数和系统参数。系统参数包括三个：
- _context
  
  输入参数，一个 JSON 字符串，其中包含了当前运行环境中的上下文信息，比如客户端 IP 地址和首选语言。
  
  目前该参数结构为：
```
{
    lang: "语言",
    ip: "IP 地址"
}
```
  语言比如：zh-CN，开发者可以根据客户端语言向用户返回目标语言的数据。根据服务器不同，IP 地址可能是 IPv4 或 IPv6。
  
  由于 _context 是一个字符串，开发者需要自己使用数据库中提供的 JSON 解析函数解析使用该参数。
- _success
  
  输出参数，一个布尔值，表示存储过程中的数据操作是否执行成功。如果将该参数设置为 false | 0，则客户端将接收到错误信息。
- _message
  
  输出参数，一个字符串，当操作失败时向客户端返回的消息。
如果目标系统中安装了沃恩提供的日志应用，可以通过 waln_log.log_op 记录用户的操作留痕信息，通常只对数据更新操作记录此类信息。默认的，Pittypat 会为所有的操作自动添加该代码。
_api.js

Pittypat 为每一个模块创建一个 _api.js 文件，该文件包含了模块中所有功能的应用服务请求 API。

以下是一个示例（Pittypat 默认创建的代码）：
/*! * 定义模块 Storage (入库管理) 中所有功能的服务 API。 * * Copyright (c), 上海沃恩信息科技有限公司. * All rights reserved. */ $(function () { 'use strict'; var // 模块的根命名空间 _mod = $$.namespace('waln.library.storage'), // 模块的 API 命名空间 _api = _mod.api = _mod.api || {}; /* * 功能 List (图书列表) 的服务 API。 * * 输入(args): * { * // 页码 * pageIndex: {int64?}, * * // 页面尺寸 * pageSize: {int64?}, * * // 排序名称 * orderName: {string(30)?}, * * // 排序方向 * orderDirection: {string(4)?}, * * // 名称 * // 查询名称中包含此文本的图书的列表。 * name: {string(50)?}, * * // 作者 * // 图书的作者姓名。 * author: {string(50)?} * } * * 输出(success.result): * { * // 总行数 * totalRows: {int64?}, * * // 图书列表 * // 符合条件的图书列表。 * books: [{ * // Id * // 图书的 Id。 * id: {uuid?}, * * // 名称 * // 图书的名称。 * name: {string?}, * * // 作者 * // 图书的作者姓名。 * author: {string?}, * * // 出版日期 * // 图书的出版日期。 * publicationDate: {date?} * }, ...] * } */ _api.list = $$.api({ // 请求路径 url: '~/waln/library/storage/list', // 请求方法：WS|WEBSOCKET、UPLOAD、UPOST|UPLOAD-POST、UWS|UPLOAD-WS、POST 之一 method: 'POST', // 对 args 进行验证 validate: function (e) { if (!e.args) { e.message = '没有提供任何参数。'; return; } // 验证 pageIndex (页码) if (!$$.util.is.long(e.args.pageIndex, 1, Long.MAX_VALUE)) { e.args.pageIndex = 1; // 默认页码 } // 验证 pageSize (页面尺寸) if (!$$.util.is.long(e.args.pageSize, 1, 10000)) { e.args.pageSize = 20; // 默认页面尺寸 } // 验证 orderName (排序名称) if (!$$.util.is.identifier(e.args.orderName)) { e.args.orderName = ''; // 默认排序名称 } // 验证 orderDirection (排序方向) if (!$$.util.is.orderDirection(e.args.orderDirection)) { e.args.orderDirection = 'asc'; // 默认排序方向 } // 验证 name (名称) if (!e.args.name) { e.message = '没有提供有效的名称。'; return; } // 验证 author (作者) if (!e.args.author) { e.message = '没有提供有效的作者。'; return; } // 空字符串表示通过验证 e.message = ''; }, // 发送给服务器的数据 data: function (e) { e.data = e.args; } }); /* * 功能 Create (添加图书) 的服务 API。 * * 输入(args): * { * // 名称 * // 图书的名称。 * name: {string(50)?}, * * // 作者 * // 图书的作者姓名。 * author: {string(50)?}, * * // 出版日期 * // 图书的出版日期。 * publicationDate: {date?} * } * * 输出(success.result): * // 新添加的图书 * // 新添加的图书信息。 * book: { * // Id * // 图书的 Id。 * id: {uuid?}, * * // 名称 * // 图书的名称。 * name: {string?}, * * // 作者 * // 图书的作者姓名。 * author: {string?}, * * // 出版日期 * // 图书的出版日期。 * publicationDate: {date?} * } */ _api.create = $$.api({ // 请求路径 url: '~/waln/library/storage/create', // 请求方法：WS|WEBSOCKET、UPLOAD、UPOST|UPLOAD-POST、UWS|UPLOAD-WS、POST 之一 method: 'POST', // 对 args 进行验证 validate: function (e) { if (!e.args) { e.message = '没有提供任何参数。'; return; } // 验证 name (名称) if (!e.args.name) { e.message = '没有提供有效的名称。'; return; } // 验证 author (作者) if (!e.args.author) { e.message = '没有提供有效的作者。'; return; } // 验证 publicationDate (出版日期) if (!$$.util.is.datetime(e.args.publicationDate, '1900/01/01', '3000/01/01')) { e.message = '没有提供有效的出版日期。'; return; } // 空字符串表示通过验证 e.message = ''; }, // 发送给服务器的数据 data: function (e) { e.data = e.args; } }); });
模块服务 Api 类

Pittypat 为每一个模块创建一个 Api.cs/java 文件，该文件包含了模块中所有功能的服务端 Api 代码，并封装为一个模块类。

以下是在 C# 中的一个示例（Pittypat 默认创建的代码）：
/*! * # 模块 Api 类: * Storage - 入库管理 * * # 描述: * 由库存管理员使用，进行入库管理功能。 * * Copyright (c), 上海沃恩信息科技有限公司. * All rights reserved. */ using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; using Pittypat; namespace Waln.Library.Storage { /// <summary> /// 提供对模块入库管理中功能的封装和调用。 /// </summary> [global::Pittypat.Module(global::Pittypat.ModulePresentation.UI, AllowAnonymous = false)] public sealed class Api : global::Pittypat.Module { #region ListAsync /// <summary> /// 模糊查询指定名称和作者的图书列表。 /// </summary> /// <param name="model">功能模型对象，其中包含了功能的参数列表、执行状态以及相关消息。</param> /// <param name="progress">跟踪和汇报异步操作的进度。</param> /// <returns>操作成功返回所有输出参数的字典，否则返回 null。</returns> public async global::System.Threading.Tasks.Task<global::Pittypat.IJson> ListAsync( global::Pittypat.FunctionModel<Args.List> model, global::Pittypat.IAsyncProgress progress) { // 执行数据操作 await this.DataService.Exec(model, progress); // 如果操作成功，返回所有输出参数的字典 return model.Success ? model.OutArgs : null; } #endregion #region CreateAsync /// <summary> /// 添加一种新的图书。 /// </summary> /// <param name="model">功能模型对象，其中包含了功能的参数列表、执行状态以及相关消息。</param> /// <param name="progress">跟踪和汇报异步操作的进度。</param> /// <returns>操作成功返回新添加的图书，否则返回 null。</returns> public async global::System.Threading.Tasks.Task<global::Pittypat.IJson> CreateAsync( global::Pittypat.FunctionModel<Args.Create> model, global::Pittypat.IAsyncProgress progress) { // 执行数据操作 await this.DataService.Exec(model, progress); // 如果操作成功，返回新添加的图书 return model.Success ? model.Args.Book : null; } #endregion } }
以下是在 Java 中的一个示例（Pittypat 默认创建的代码）：
/* * # 模块 Api 类: * Storage - 入库管理 * * # 描述: * 由库存管理员使用，进行入库管理功能。 * * Copyright (c), 上海沃恩信息科技有限公司. * All rights reserved. */ package com.waln.library.storage; /** * 提供对模块入库管理中功能的封装和调用。 */ @pittypat.ModuleAnnotation(presentation = pittypat.ModulePresentation.UI, allowAnonymous = false) public final class Api extends pittypat.Module { /** * 模糊查询指定名称和作者的图书列表。 * * @param model 功能模型对象，其中包含了功能的参数列表、执行状态以及相关消息。 * @param progress 跟踪和汇报异步操作的进度。 * * @return pittypat.IJson 操作成功返回所有输出参数的字典，否则返回 null。 */ public pittypat.IJson list( pittypat.FunctionModel<com.waln.library.storage.args.List> model, pittypat.IAsyncProgress progress) { // 执行数据操作 this.getDataService().exec(model, progress); // 如果操作成功，返回所有输出参数的字典 return model.isSuccess() ? model.getOutArgs() : null; } /** * 添加一种新的图书。 * * @param model 功能模型对象，其中包含了功能的参数列表、执行状态以及相关消息。 * @param progress 跟踪和汇报异步操作的进度。 * * @return pittypat.IJson 操作成功返回新添加的图书，否则返回 null。 */ public pittypat.IJson create( pittypat.FunctionModel<com.waln.library.storage.args.Create> model, pittypat.IAsyncProgress progress) { // 执行数据操作 this.getDataService().exec(model, progress); // 如果操作成功，返回新添加的图书 return model.isSuccess() ? model.getArgs().book : null; } }
所有表

Pittypat 为每一个模块创建一个 tables.sql 文件，文件内容是空的，以便开发人员编写针对该模块的数据库初始化代码。

以下是针对 MySQL 数据库的一个示例（Pittypat 默认创建的代码）：
/* * # 应用所有数据库表: * Library - 图书管理系统 * * # 描述: * 图书管理系统提供图书的入库管理和借阅管理，图书入库由图书管理员使用，而借阅由所有注册用户使用。 * * Copyright (c), 上海沃恩信息科技有限公司. * All rights reserved. */ -- 确保架构存在 create schema if not exists "waln_library" character set utf8mb4 collate utf8mb4_unicode_ci; use "waln_library"; /* * # 辅助函数: * _pittypat_table_exists - 检查指定的表是否已经存在 * * # 描述: * 检查指定的表是否已经存在。 */ drop function if exists "waln_library"."_pittypat_table_exists"; delimiter // create function "waln_library"."_pittypat_table_exists"(tbl varchar(30)) returns bool not deterministic begin if tbl is not null and tbl <> '' and exists (select * from "information_schema"."tables" where "table_schema" = 'waln_library' and "table_name" = tbl) then return true; else return false; end if; end // delimiter ; /* * # 辅助函数: * _pittypat_column_exists - 检查指定的列是否已经存在 * * # 描述: * 检查指定的列是否已经存在。 */ drop function if exists "waln_library"."_pittypat_column_exists"; delimiter // create function "waln_library"."_pittypat_column_exists"(tbl varchar(30), col varchar(30)) returns bool not deterministic begin if tbl is not null and tbl <> '' and col is not null and col <> '' and exists (select * from "information_schema"."columns" where "table_schema" = 'waln_library' and "table_name" = tbl and "column_name" = col) then return true; else return false; end if; end // delimiter ; /* * # 辅助函数: * _pittypat_index_exists - 检查指定的索引是否已经存在 * * # 描述: * 检查指定的索引是否已经存在。 */ drop function if exists "waln_library"."_pittypat_index_exists"; delimiter // create function "waln_library"."_pittypat_index_exists"(tbl varchar(30), idx varchar(63)) returns bool not deterministic begin if tbl is not null and tbl <> '' and idx is not null and idx <> '' and exists (select * from "information_schema"."statistics" where "table_schema" = 'waln_library' and "table_name" = tbl and "index_name" = idx) then return true; else return false; end if; end // delimiter ; /* * # 数据库表 - MySql: * Books - 图书 * * # 描述: * 表示一种图书的相关信息。 */ drop procedure if exists "waln_library"."_pittypat_replace_table"; delimiter // create procedure "waln_library"."_pittypat_replace_table"() begin if not "waln_library"."_pittypat_table_exists"('Books') then create table "waln_library"."Books" ( "PK" bigint not null auto_increment primary key, -- 主键 "Id" binary(16) not null, -- Id "Name" varchar(50) not null, -- 名称 "Author" varchar(50) not null, -- 作者 "PublicationDate" date not null -- 出版日期 ); -- 索引 U_Books_Id alter table "Books" add constraint unique index "U_Books_Id" ( "Id" asc ); else -- 列 Id if not "_pittypat_column_exists"('Books', 'Id') then alter table "Books" add column "Id" binary(16) not null after "PK"; else alter table "Books" modify column "Id" binary(16) not null after "PK"; end if; -- 列 Name if not "_pittypat_column_exists"('Books', 'Name') then alter table "Books" add column "Name" varchar(50) not null after "Id"; else alter table "Books" modify column "Name" varchar(50) not null after "Id"; end if; -- 列 Author if not "_pittypat_column_exists"('Books', 'Author') then alter table "Books" add column "Author" varchar(50) not null after "Name"; else alter table "Books" modify column "Author" varchar(50) not null after "Name"; end if; -- 列 PublicationDate if not "_pittypat_column_exists"('Books', 'PublicationDate') then alter table "Books" add column "PublicationDate" date not null after "Author"; else alter table "Books" modify column "PublicationDate" date not null after "Author"; end if; -- 删除索引 U_Books_Id if "_pittypat_index_exists"('Books', 'U_Books_Id') then alter table "Books" drop index "U_Books_Id"; end if; -- 创建索引 U_Books_Id alter table "Books" add constraint unique index "U_Books_Id" ( "Id" asc ); end if; end // delimiter ; call "waln_library"."_pittypat_replace_table"(); drop procedure "waln_library"."_pittypat_replace_table"; /* select "Id", -- Id "Name", -- 名称 "Author", -- 作者 "PublicationDate" -- 出版日期 from "waln_library"."Books" where "Id" = $id; insert into "waln_library"."Books" ( "Id", -- Id "Name", -- 名称 "Author", -- 作者 "PublicationDate" -- 出版日期 ) values ( $id, -- Id $name, -- 名称 $author, -- 作者 $publicationDate -- 出版日期 ); update "waln_library"."Books" set "Id" = $id, -- Id "Name" = $name, -- 名称 "Author" = $author, -- 作者 "PublicationDate" = $publicationDate -- 出版日期 where "Id" = $id; delete from "waln_library"."Books" where "Id" = $id; */ -- 移除辅助函数和存储过程 drop procedure if exists "waln_library"."_pittypat_replace_table";
数据库全局函数

Pittypat 为每一个模块创建一个 local.sql 文件，文件内容是空的，以便开发人员编写针对该模块的公共的视图、函数或存储过程。

以下是针对 MySQL 数据库的一个示例（Pittypat 默认创建的代码）：
/* * # 应用公共代码: * Library - 图书管理系统 * * # 描述: * 图书管理系统提供图书的入库管理和借阅管理，图书入库由图书管理员使用，而借阅由所有注册用户使用。 * * Copyright (c), 上海沃恩信息科技有限公司. * All rights reserved. */ use "waln_library"; /* * # 公共函数: * to_suuid - 将通过 uuid() 创建的 char(36) uuid 转换为 binary(16) uuid * * # 描述: * 将通过 uuid() 创建的 char(36) uuid 转换为 binary(16) uuid，保持十六进制字符的先后顺序不变。 */ drop function if exists "waln_library"."to_buuid"; delimiter // create function "waln_library"."to_buuid"(id char(36)) returns binary(16) deterministic begin return unhex(replace(id, '-', '')); end // delimiter ; /* * # 公共函数: * from_buuid - 将 binary(16) uuid 转换为 char(36) uuid * * # 描述: * 将 binary(16) uuid 转换为 char(36) uuid，保持十六进制字符的先后顺序不变。 */ drop function if exists "waln_library"."from_buuid"; delimiter // create function "waln_library"."from_buuid"(id binary(16)) returns char(36) deterministic begin return insert(insert(insert(insert(hex(id), 9, 0, '-'), 14, 0, '-'), 19, 0, '-'), 24, 0, '-'); end // delimiter ; /* * # 公共函数: * buuid - 生成一个新的 binary(16) uuid * * # 描述: * 生成一个新的 binary(16) uuid */ drop function if exists "waln_library"."buuid"; delimiter // create function "waln_library"."buuid"() returns binary(16) not deterministic begin return unhex(replace(uuid(), '-', '')); end // delimiter ; /* * # 公共函数: * to_suuid - 将通过 uuid() 创建的 char(36) uuid 转换为按时间排序的 binary(16) uuid * * # 描述: * 将通过 uuid() 创建的 char(36) uuid 转换为 binary(16) uuid，将 uuid 中的时间值移动到最前面，使得 uuid 具有按时间进行排序的特性。 */ drop function if exists "waln_library"."to_suuid"; delimiter // create function "waln_library"."to_suuid"(id char(36)) returns binary(16) deterministic begin return unhex(concat(substr(id, 15, 4), substr(id, 10, 4), substr(id, 1, 8), substr(id, 20, 4), substr(id, 25))); end // delimiter ; /* * # 公共函数: * from_suuid - 将已按时间排序的 binary(16) uuid 转换为 char(36) uuid * * # 描述: * 将已按时间排序的 binary(16) uuid 转换为 char(36) uuid，调整时间值的位置以还原原来通过 uuid() 创建的值。 */ drop function if exists "waln_library"."from_suuid"; delimiter // create function "waln_library"."from_suuid"(id binary(16)) returns char(36) deterministic begin declare s varchar(36); set s = hex(id); return concat(substr(s, 9, 8), '-', substr(s, 5, 4), '-', substr(s, 1, 4), '-', substr(s, 17, 4), '-', substr(s, 21)); end // delimiter ; /* * # 公共函数: * suuid - 生成一个新的按时间排序的 binary(16) uuid * * # 描述: * 生成一个新的按时间排序的 binary(16) uuid。 */ drop function if exists "waln_library"."suuid"; delimiter // create function "waln_library"."suuid"() returns binary(16) not deterministic begin return "waln_library"."to_suuid"(uuid()); end // delimiter ; /* * # 公共函数: * uuid_to_b64 - 将 binary(16) uuid 转换为对 URI 友好的 base64 字符串 char(22) * * # 描述: * 将 binary(16) uuid 转换为对 URI 友好的 base64 字符串 char(22)。 * 大多数情况下，客户端使用 base64 char(22)，如果要向客户端返回字符串格式的 uuid，应该使用该函数对 uuid 进行转换。 */ drop function if exists "waln_library"."uuid_to_b64"; delimiter // create function "waln_library"."uuid_to_b64"(id binary(16)) returns char(22) deterministic begin return replace(replace(substr(to_base64(id), 1, 22), '/', '_'), '+', '-'); end // delimiter ; /* * # 公共函数: * b64_to_uuid - 将对 URI 友好的 base64 char(22) uuid 转换为 binary(16) * * # 描述: * 将对 URI 友好的 base64 char(22) uuid 转换为 binary(16)。 * 如果从客户端传来的值是 base64 char(22)，则应该使用该函数将字符串转换为 uuid。 */ drop function if exists "waln_library"."b64_to_uuid"; delimiter // create function "waln_library"."b64_to_uuid"(id char(22)) returns binary(16) deterministic begin return from_base64(concat(replace(replace(id, '-', '+'), '_', '/'), '==')); end // delimiter ; /* * # 公共函数: * like_escape - 转义用于 LIKE 运算符的字符串 * * # 描述: * 转义用于 LIKE 运算符的字符串： * 如果字符串是 null 或空字符串，则返回 '%'， * 否则替换字符串中的 '_' 和 '%'，并在字符串前面和后面分别添加 '%'。 */ drop function if exists "waln_library"."like_escape"; delimiter // create function "waln_library"."like_escape"(s text) returns text deterministic begin return if(s is null or s = '', null, concat('%', replace(replace(s, '_', '_'), '%', '%'), '%')); end // delimiter ;
数据库初始化

Pittypat 为每一个模块创建一个 init.sql 文件，文件内容是空的，以便开发人员编写针对该模块的数据库初始化代码。

以下是针对 MySQL 数据库的一个示例（Pittypat 默认创建的代码）：
/* * # 描述: * 注册 App 和其中包含的功能模块，以便能够对这些模块进行权限管理，以及展示导航列表。 * 如果不使用沃恩提供的组织和用户（Waln.Authority），以下创建 App 和模块的代码可以全部删除，或替换为你自己的初始化代码。 * * Copyright (c), 上海沃恩信息科技有限公司. * All rights reserved. */ use "waln_authority"; -- 注册应用：图书管理系统 call "waln_authority"."reg_app" ( 'znuuLY43Eee8O5gWoeWZUA', -- 应用 Id 'Waln', -- 开发者代码 '上海沃恩信息科技有限公司', -- 开发者名称 'Library', -- 应用标识符 '图书管理系统', -- 应用名称 '1.0.1.0', -- 应用版本号 1, -- 模块数目 concat('图书管理系统提供图书的入库管理和借阅管理，图书入库由图书管理员使用，而借阅由所有注册用户使用。'), -- 描述 null -- 位置，传递 null 自动使用最大值 + 1 ); -- 注册模块：入库管理 call "waln_authority"."reg_module" ( 'h-xRJY4-Eee8O5gWoeWZUA', -- 模块 Id 'znuuLY43Eee8O5gWoeWZUA', -- 隶属应用 Id 0, -- 模块位置 'Storage', -- 模块标识符 '入库管理', -- 模块名称 1, -- 呈现方式：0-不公开，1-UI，2-服务 false, -- 是否允许匿名访问 concat('由库存管理员使用，进行入库管理功能。') -- 描述 ); use "waln_library";
所有视图

Pittypat 为每一个模块创建一个 views.sql 文件，该文件包含了所有对象视图的代码。

以下是针对 MySQL 数据库的一个示例（Pittypat 默认创建的代码）：
/* * # 应用所有视图: * Library - 图书管理系统 * * # 描述: * 图书管理系统提供图书的入库管理和借阅管理，图书入库由图书管理员使用，而借阅由所有注册用户使用。 * * Copyright (c), 上海沃恩信息科技有限公司. * All rights reserved. */ use "waln_library"; /* * # 对象视图 - MySql: * v_storage_book - 图书 * * # 描述: * 表示一种图书的相关信息。 */ create or replace view "waln_library"."v_storage_book" as select b."Id", -- Id b."Name", -- 名称 b."Author", -- 作者 b."PublicationDate" -- 出版日期 from "waln_library"."books" b;
所有存储过程

Pittypat 为每一个模块创建一个 procedures.sql 文件，该文件包含了所有功能存储过程的代码。

以下是针对 MySQL 数据库的一个示例（Pittypat 默认创建的代码）：
/* * # 应用所有存储过程: * Library - 图书管理系统 * * # 描述: * 图书管理系统提供图书的入库管理和借阅管理，图书入库由图书管理员使用，而借阅由所有注册用户使用。 * * Copyright (c), 上海沃恩信息科技有限公司. * All rights reserved. */ use "waln_library"; /* * # 存储过程 - MySql: * p_storage_list - 图书列表 * * # 描述: * 模糊查询指定名称和作者的图书列表。 */ drop procedure if exists "waln_library"."p_storage_list"; delimiter // create procedure "waln_library"."p_storage_list" ( in $userId binary(16), -- 当前用户 Id in $pageIndex bigint, -- 页码 in $pageSize bigint, -- 页面尺寸 out $totalRows bigint, -- 总行数 in $orderName varchar(30), -- 排序名称 in $orderDirection varchar(4), -- 排序方向 in $name varchar(50), -- 名称 in $author varchar(50), -- 作者 in $_context text, -- 当前环境变量参数 out $_success bool, -- 指示操作是否成功 out $_message text -- 操作中产生的消息 ) _proc_body: begin -- 主键 -- declare $pk bigint default null; -- Id -- declare $id binary(16) default null; -- 当前日期时间 -- declare $now datetime default current_timestamp; -- 默认指示操作失败 set $_success = 0; set $_message = ''; -- 初始化 out 参数 $totalRows (总行数) set $totalRows = 0; -- 验证参数 $userId (当前用户 Id) if $userId is null then set $_message = '没有提供有效的当前用户 Id。'; leave _proc_body; end if; -- 验证参数 $pageIndex (页码) if $pageIndex is null or $pageIndex < 1 then -- 默认分页查询的页码，从 1 开始 set $pageIndex = 1; end if; -- 验证参数 $pageSize (页面尺寸) if $pageSize is null or $pageSize < 1 then -- 默认分页查询的页面尺寸 set $pageSize = 20; end if; -- 验证参数 $orderName (排序名称) if $orderName is null or $orderName = '' or $orderName not in ( -- 确保排序名称是以下名称之一，防止 SQL 注入式攻击 'Name', 'Author' ) then -- 默认排序列 set $orderName = ''; end if; -- 验证参数 $orderDirection (排序方向) if $orderDirection is null or $orderDirection not in ('asc', 'desc') then -- 默认排序方向 set $orderDirection = 'asc'; end if; -- 验证参数 $name (名称) if $name is null or $name = '' then set $_message = '没有提供名称。'; leave _proc_body; end if; -- 验证参数 $author (作者) if $author is null or $author = '' then set $_message = '没有提供作者。'; leave _proc_body; end if; -- 返回 List.books：图书列表 set @_page_sql = concat( 'select sql_calc_found_rows ', 'v.* ', 'from ', '"waln_library"."v_storage_book" v ', 'where ', '((? is null) or (v."Name" like ?)) and ', '((? is null) or (v."Author" like ?)) ', 'order by ', 'v."', $orderName, '" ', $orderDirection, ' ', 'limit ', cast((($pageIndex - 1) * $pageSize) as char), -- 起始行号 ',', cast($pageSize as char)); -- 页面尺寸（最多查询的行数） -- 为分页查询准备参数值 set @$name = "waln_library"."like_escape"($name); -- 名称 set @$author = "waln_library"."like_escape"($author); -- 作者 -- 准备分页查询命令 prepare __stmt from @_page_sql; -- 执行分页查询命令 execute __stmt using @$name, -- 名称 @$name, -- 名称 @$author, -- 作者 @$author; -- 作者 -- 释放分页查询命令占用的资源 deallocate prepare __stmt; set @_page_sql = null; -- 返回 List.totalRows：总行数 set $totalRows = found_rows(); -- 指示操作成功 set $_success = 1; -- 记录操作日志 set @_log_id = null; call "waln_log"."log_op" ( $userId, -- 当前用户的 Id 1, -- 操作类型代码组合：1-查询、2-添加、4-更新、8-删除、16-其他 'waln_library.books', -- 相关数据库表的名称列表 'waln_library.p_storage_list', -- 存储过程名称 $_success, -- 指示操作是否成功 concat('模糊查询指定名称和作者的图书列表。'), -- 详细的操作描述 $_context, -- 当前环境变量参数 @_log_id -- 日志消息的 Id ); end // delimiter ; /* * # 存储过程 - MySql: * p_storage_create - 添加图书 * * # 描述: * 添加一种新的图书。 */ drop procedure if exists "waln_library"."p_storage_create"; delimiter // create procedure "waln_library"."p_storage_create" ( in $userId binary(16), -- 当前用户 Id in $name varchar(50), -- 名称 in $author varchar(50), -- 作者 in $publicationDate date, -- 出版日期 in $_context text, -- 当前环境变量参数 out $_success bool, -- 指示操作是否成功 out $_message text -- 操作中产生的消息 ) _proc_body: begin -- 主键 -- declare $pk bigint default null; -- Id -- declare $id binary(16) default null; -- 当前日期时间 -- declare $now datetime default current_timestamp; -- 默认指示操作失败 set $_success = 0; set $_message = ''; -- 验证参数 $userId (当前用户 Id) if $userId is null then set $_message = '没有提供有效的当前用户 Id。'; leave _proc_body; end if; -- 验证参数 $name (名称) if $name is null or $name = '' then set $_message = '没有提供名称。'; leave _proc_body; end if; -- 验证参数 $author (作者) if $author is null or $author = '' then set $_message = '没有提供作者。'; leave _proc_body; end if; -- 验证参数 $publicationDate (出版日期) if $publicationDate is null then set $_message = '没有提供出版日期。'; leave _proc_body; end if; insert into "waln_library"."books" ( "Name", "Author", "PublicationDate" ) values ( $name, $author, $publicationDate ); -- 返回 Create.book：新添加的图书 select v.* from "waln_library"."v_storage_book" v where v."Name" = $name and v."Author" = $author and v."PublicationDate" = $publicationDate limit 1; -- 指示操作成功 set $_success = 1; -- 记录操作日志 set @_log_id = null; call "waln_log"."log_op" ( $userId, -- 当前用户的 Id 2, -- 操作类型代码组合：1-查询、2-添加、4-更新、8-删除、16-其他 'waln_library.books', -- 相关数据库表的名称列表 'waln_library.p_storage_create', -- 存储过程名称 $_success, -- 指示操作是否成功 concat('添加一种新的图书。'), -- 详细的操作描述 $_context, -- 当前环境变量参数 @_log_id -- 日志消息的 Id ); end // delimiter ;
输出源代码
在编码页面右上角，用户头像对应的下拉菜单中包含一个 输出应用 的菜单项，点击该菜单项可以输出整个应用。

Pittypat 会将一个应用输出为一个完整的 Visual Studio 解决方案，或者适合于 Java 开发环境的 Maven 工程，其中包含源代码、文档以及其他相关的资源。解决方案将被打包为一个可下载的压缩包，解压缩后可以使用相应的 IDE 打开使用。解决方案或工程中仅包含当前用户有权限查看和编码的模块。输出 App 时需要填写如下的选项：
1. 用户前端
  
  H5 Web、微信小程序、Android 或 iOS 原生应用。目前已支持 H5 Web。
2. 应用服务
  
  应用服务的类型，可以是 Java 或 C#。如果在创建应用时只选择了一种语言，这里的选项就是禁用的。
3. 数据服务
  
  目标数据服务的类型，可以是 MySQL、SQL SERVER 或 ORACLE。如果在创建应用时只选择了一种数据库，这里的选项就是禁用的。
编写源代码
Pittypat 提供在浏览器中编写和保存代码的支持，并且支持语法高亮显示源代码，但是不支持对源代码的编译功能，也不支持智能感知功能。通常开发人员会在本地 IDE 中编写代码，调试通过后再将源代码粘贴到浏览器提交保存。Pittypat 在输出代码时会将开发人员提交保存的代码与自动输出的代码合并。

源代码在提交前会首先进行压缩，压缩后最大支持的长度为 2M 字节，因此建议源代码的总长度不超过 2M，最大略微超过 2M。
1. 填空式编码
  
  功能的 Api 方法代码、存储过程代码，对象的视图代码都采用填空式的编码方式。因为，功能方法声明、存储过程声明、视图声明都是不允许修改的。开发者只需要编写方法实现代码、存储过程实现代码和视图实现代码即可。
2. HTML
  
  Pittypat 使用 HTML5 作为开发 html 的语言，App 的目标运行浏览器应该提供对 HTML5 协议的支持。
  
  关于 HTML5 的参考请参见 MDN 上的 HTML5 （可能包含英文内容）。
3. CSS
  
  Pittypat 使用 CSS3 作为开发 CSS 的语言，App 的目标运行浏览器应该提供对 CSS3 协议的支持。目前 Pittypat 还不支持直接在浏览器中编写 SASS、LESS 等代码，如果需要使用 SASS 或 LESS，开发者可以在本地 IDE 中编写 SASS 或 LESS，并在本地编译成 CSS 后再提交到 Pittypat。
  
  关于 CSS3 的参考请参见 MDN 上的 CSS3 （可能包含英文内容）。
4. JS
  
  Pittypat 使用 ECMAScript 5.1 或以上版本标准的 JavaScript，目前所有主流浏览器至少都支持 ECMAScript 5.1。开发者可以使用 ES6，甚至 ES7 的新特性，但是应该保证 App 的目标运行环境支持这些新的特性。
  
  关于 CSS3 的参考请参见 MDN 上的 JavaScript （可能包含英文内容）。
5. C#
  
  Pittypat 使用 C# 5.0+ 语言规范，相对应的 .NET Framework 版本为 4.5.2+。开发者应该考虑使用 VS 2015 作为首选开发环境。
  
  Pittypat 深度定制 Web API，取消了 MVC 中的 Controller，请求会被直接路由到模块的 Api 类。
  
  关于 C# 语言请参见 MSDN 上的 C# 语言规范（可能包含英文内容）。
  
  关于 .NET Framework 4.5.2 请参见 .NET Framework 4.5.2 下载。
  
  关于 VS 2015 请参见 VS 2015 社区版。
6. Java
  
  Java 取消了传统 MVC 中的 Controller，请求会被直接路由到模块的 Api 类。
7. SQL
  
  Pittypat 已支持 3 种数据库的 SQL 代码编写：MySQL、MS SQL SERVER、ORACLE，未来将支持更多数据库。
  
  所有的标识符默认一律使用 " （双引号）引用，这是因为 " 是 ANSI 规范，所有数据库都支持，当进行数据库移植时能够提供最大的便利。
输出文档
目前，Pittypat 输出数据库设计说明书、详细设计说明书和帮助手册。其他文档将陆续提供。
1. 数据库设计说明书和详细设计说明书
  
  这两个文档都是通过客户端 JS 生成的 .html 文件，而不是 Word 文件。开发者可以直接打印文件，也可以将 HTML 复制到 Word 中创建 .doc 或 .docx 文件。这两个文件都不需要人工修改，最多是在 Word 中创建目录和封面。
2. 帮助手册
  
  Pittypat 为每一个模块、每一个功能创建了在线帮助页面，每一个模块的帮助页面位于 web/com/{开发者标识符}/{应用标识符}/{模块标识符}/help 目录下。Pittypat 已经将每一个功能页面的帮助按钮链接到了帮助页面中的相应位置，开发者只需要完善帮助页面，并将每一个功能的截图按照功能标识符的 camel 格式存放在 help/images 目录下即可。帮助页面可以直接打印，因此可以用作验收需要的提交文档。
请参见
- 应用
- 设计
- 配置

编码

源代码组织

Android AppShell

C#

Java

SQL

Web

人工编码量

表

对象 UI JS

bind()

语法

args

model

$model

返回值

html

语法

返回值

show()

语法

args

model

$context

返回值

rowHtml

语法

返回值

insert()

语法

args

model

pos

$list

返回值

示例

insertAll()

语法

args

models

pos

$list

返回值

示例

update()

语法

args

model

$model

$list

返回值

示例

remove()

语法

args

model

$list

示例

paging()

语法

args

total

rows

$context

示例

rowsChanged()

语法

rows

$context

示例

对象实体类

对象视图

功能 HTML

功能 JS

功能实体类

功能 API

功能存储过程

_api.js

模块服务 Api 类

所有表