=encoding UTF-8

=head1 NAME

OpenResty::Tutorial::GettingStarted_cn - 中文版快速入门教程

=head1 DESCRIPTION

=head2 申请 OpenResty 帐户

OpenResty 帐户是以应用为单位的。一般来说，每一个应用都应注册一个独立的 OpenResty 帐户。目前注册帐户的方法是写信给我们：C<agentzh@yahoo.cn>.

请在来信中附上你希望的帐户名（全部小写字母加数字）以及 Admin 角色的初始密码。一般来说，我们创建的帐户都位于下面这个服务器：C<api.openresty.org>.

=head2 管理 OpenResty 帐户

应用开发人员一般使用 Admin 角色来管理她的 OpenResty 帐户。该角色是密码登录方式。

OpenResty 本身是 100% 基于 Web Service 的，所以技术上讲完全可以使用包括 curl 和 Firefox 这样的 HTTP 客户端来管理你的帐户。但站长们一般都选择使用一个现成的基于 Web 的管理站点：

L<http://openresty.org/admin/>

用你的帐户名和 Admin 密码登录之后，你会看到它的主界面：

=begin html

<!-- this h1 part is for search.cpan.org -->
<h1>
<a class = 'u'
   href  = '#___top'
   title ='click to go to top of document'
   name  = "PNG IMAGE"
>PNG IMAGE</a>
</h1>

<p><img src="http://agentzh.org/misc/admin-index.png" border=2 alt="Admin main UI at agentzh.org"/></p>
<p>Image hosted by <a href="http://agentzh.org">agentzh.org</a></p>

=end html

L<http://agentzh.org/misc/admin-index.png>

此时你会看到主菜单中有 Models, Views, Roles, Actions, Feeds 等项目。

=head3 Model选项卡

Models 选项卡是用来对 OpenResty Model 对象进行管理的。OpenResty Model 在逻辑上类似于数据库中的 table. 通过该 Models 选项卡中的界面，你可以创建新的 Model, 修改、查看或者删除已有的 Model 对象。

每个 Model 对象都有若干属性，比如 C<name>, C<description> 之类的。其中最重要的是 C<columns> 属性。它定义了 Model （或者说数据表）中的列。

第个列都需要指定一个列名（name），一个标签（label ），一个类型（type），以及一个可选的缺省值。注意包括 Model 名，列名在内的所有 OpenResty 的对象的名字都是大小写敏感的。

绝大多数常见的 Pg 数据类型都可以在 OpenResty 的列类型中使用，比如下面这些例子： C<bigint>, C<cidr>, C<inet>, C<ip4r>, C<macaddr>, C<tsquery>, C<tsvector>, C<bit (5)>, C<boolean>, C<text>, C<varchar (3)>, C<integer>, C<serial>, C<real>, C<double precision>, C<ltree>, C<date>, C<timestamp (0) with time zone>, C<timestamp (2) without time zone>, C<interval>.

在 Model 选项卡中可以修改已有的定义，只需要用B<鼠标单击>要修改的值就可以了。

创建好的 Model 列表可以直接在浏览器或者 curl 中查看，例如

  http://api.openresty.org/=/model?_user=foo.Admin&_password=PASSWORD

这里 C<foo> 是你的帐户名，而 C<PASSWORD> 则是你的 Admin 角色的密码的 MD5。得到的结果应该是 model 列表的 JSON 表示。一个典型的输出是：

  [{"src":"/=/model/YahooStaff","name":"YahooStaff","description":"Yahoo! China Staff"},{"src":"/=/model/IrcLog","name":"IrcLog","description":"IRC Log"}]

如果在 URL 主体后面加上 .yml 后缀，则能看到可读性更好的 YAML 表示：

  GET /=/model.yml?_user=foo.Admin&_password=PASSWORD

一次典型的输出是

  --- 
  - 
    description: Yahoo! China Staff
    name: YahooStaff
    src: /=/model/YahooStaff
  - 
    description: IRC Log
    name: IrcLog
    src: /=/model/IrcLog

获取密码明文对应的 MD5 的方法有很多，我们经常用的两种方法是：

=over

=item 1.

在 UNIX shell 中输入命令

    echo -n 'my_password' | md5sum

=item 2.

在 PostgreSQL 的 psql 终端中输入命令

    select md5('my_password');

=back

这里的 my_password 就是你的密码明文。

利用 Admin 站点的 Models 选项卡还可以完成记录插入操作。但是其界面一次只允许插入一条记录。如果你有大量的记录需要导入到 Model，见参见[[OpenResty_数据导入]]一文。

有关 Model 使用的更多信息请参见

L<OpenResty::Spec::REST_cn/Models>

以及

L<OpenResty::Spec::Overview/Models>

=head3 Views选项卡

通过Views选项卡，可以创建和管理你帐户中的 View 对象。View 对象的定义本质是一种带参量的“迷你 SQL”查询。假设前面我们创建了一个名叫 C<Persion> 的 Model, 它拥有 C<name>, C<age>, 和 C<gender> 这三个列。那么我们可以为它创建一个拥有以下定义的 View 对象：

  select name, age
  from Student
  where name = $name and age >= $age

这里 name 和 age 都是参量。

在创建了这个名为 FindStudent 的 View 对象之后，我们可以通过 HTTP 来调用 View 对象，从而执行其对应的参数化的查询:

  GET /=/view/FindStudent/~/~?name=李明&age=35&_user=foo.Admin&_password=PASSWORD

就将返回 FindStudent 中年龄在 35 岁以上的名叫“李明”的记录列表（JSON格式）。

这里使用的“迷你SQL”语言叫做 RestyScript. 视图中使用的 RestyScript 是 SQL 的一个非严格子集，而且是大小写敏感的。

有关 View 使用的更多信息请参见

L<OpenResty::Spec::REST_cn/Views>

以及

L<OpenResty::Spec::Overview/Views>

=head2 调用OpenResty接口

基于 OpenResty 的应用大致分以下两类：

=over

=item 1.

基于 PHP/Java 的服务器端应用,

=item 2.

基于纯 JS 的 AJAX 应用.

=back

第一类应用的代表是我们全能搜索的菜名搜索功能模块：

L<http://ysearchblog.cn/2008/06/post_120.html>

使用其语言自身的 HTTP 客户端库和 JSON 库完成对 OpenResty 服务的调用。

第二类应用的代表是我的 blog 网站：

L<http://blog.agentzh.org>

一般使用我们的 C<openresty.js> 库：

L<http://svn.openfoundry.org/openapi/trunk/clients/js/>

=head1 AUTHOR

Agent Zhang (agentzh) C<< <agentzh@yahoo.cn> >>

=head1 SEE ALSO

L<OpenResty::Spec::REST_cn>, L<OpenResty::Spec::Overview>, L<OpenResty>.