web.py 快速入门：8 行代码构建你的第一个 Python Web 应用

• 后端
• Web框架

web.py 是一个"简单而强大"的 Python Web 框架，其官方文档入口 docs/index.rst 用一段仅 8 行的代码展示了从零开始搭建 Web 应用的完整路径。本文以该快速入门示例为核心，逐行拆解 URL 路由、应用对象、处理器类与内置服务器的底层实现（对应源码 web/application.py、web/wsgi.py 与 web/httpserver.py），并串联官方文档树中的用户输入、数据库、模板、部署等进阶主题。读完本文，你将能够独立编写、运行并调试你的第一个 web.py 应用，并清楚后续深入学习的文档入口。

一、写在前面：web.py 是什么

web.py 是 Python 生态中历史悠久的轻量级 Web 框架，其核心设计理念是"as simple as it is powerful"（简单而强大）。从当前仓库的 README.md 可知，安装方式只需一条命令：

python3 -m pip install web.py

整个框架代码集中在仓库根目录的 web/ 包中，其公开 API 通过 web/init.py 统一导出（该文件同时标注了当前仓库版本号为0.76，作者为 Aaron Swartz 与 Anand Chitipothu）。你只需import web，即可访问web.application、web.input、web.database、web.template等全部核心能力。

二、Hello World：8 行代码的完整示例

官方文档 docs/index.rst 的 Getting Started 章节给出了最简应用。把下面这段代码保存为hello.py，然后执行python hello.py，浏览器访问http://localhost:8080/即可看到 "Hello, world!"：

import web urls = ("/.*", "hello") app = web.application(urls, globals()) class hello: def GET(self): return 'Hello, world!' if __name__ == "__main__": app.run()

这个例子虽短，却完整覆盖了 web.py 应用的五个核心要素：路由表（urls）、应用对象（app）、处理器类（hello）、HTTP 方法分发（GET）与内置服务器启动（app.run()）。下面逐层拆解。

1. 路由表urls：正则到处理器的映射

urls是一个元组，按"URL 正则模式 → 处理器类名"两两成对组织：

urls = ("/.*", "hello")

这里/.*是一个正则表达式，匹配任意路径（包括根路径/），"hello" 则指向当前模块中定义的hello类。从 application.py 的实现可以看到，这个成对元组在init_mapping中通过utils.group(mapping, 2)被两两分组为内部映射表；add_mapping则允许运行时追加新的路由项。

需要注意的是，匹配顺序就是元组声明顺序：web.py 按顺序尝试每个模式，命中即停止，因此更具体的路由应放在前面。例如测试文件 tests/test_application.py 中的test_routing展示了urls = ("/foo", "foo")后访问/foo返回foo；testUppercaseMethods则验证了只定义GET的类被以internal方法请求时会返回405 Method Not Allowed。此外urls中的模式支持正则分组与反向引用，tests/test_application.py的testRedirect中"/b/(.*)", r"redirect /hello/\1"即为一例——\1会把匹配到的分组原样拼入重定向目标。

2. 应用对象app = web.application(urls, globals())

web.application是 web.py 的核心类，构造时接收两个参数：

• mapping：路由元组；
• fvars：处理器类的查找命名空间。传入globals()意味着框架会在当前模块的全局命名空间中按名字找到hello类并实例化调用。

从 application.py 的构造函数可以看到，创建应用时还会自动挂载loadhook与unloadhook两个处理器，分别负责在请求进入时把当前应用压入web.ctx.app_stack、在请求结束时弹出（application.py），这是 web.py 支持子应用嵌套与上下文管理的基础。此外，构造函数第三个可选参数autoreload控制是否启用源码改动自动重载，默认取web.config中的debug值；tests/test_application.py的test_reloader与test_reloader_nested专门验证了修改类实现或路由表后，无需重启进程即可看到新结果。

3. 处理器类hello：HTTP 方法即方法名

web.py 的请求处理遵循"方法名映射"约定：类中的GET、POST、PUT、DELETE等大写方法对应同名 HTTP 方法。当请求到达/时，路由命中hello，框架实例化该类并调用其GET方法，返回值即响应体。

class hello: def GET(self): return 'Hello, world!'

这一定义无需继承任何基类、无需装饰器标注，普通类即可成为处理器——这是 web.py 极简风格的代表性设计。若处理器需要捕获 URL 中的正则分组，只需给方法添加对应数量的参数，例如urls = ("/(.*)", "echo")时def GET(self, name)即可拿到路径参数（该用法同时出现在 application.py 的add_processor文档示例与test_subdirs测试中）。

4.app.run()：一行启动内置服务器

if __name__ == "__main__": app.run()

if __name__ == "__main__"保证仅当直接执行python hello.py时才启动服务器，模块被导入时则不启动。

app.run()的调用链值得展开：首先由 application.py 的run方法调用self.wsgifunc(*middleware)把 web.py 应用包装为标准 WSGI 函数（可在此传入中间件），随后交给 wsgi.py 的runwsgi决定以何种方式运行：

• 若环境中存在SERVER_SOFTWARE（CGI 环境）或命令行带fcgi/fastcgi/scgi参数，则分别走 CGI / FastCGI / SCGI 协议适配路径；
• 否则读取sys.argv的第一个参数作为端口号（无参数时默认 8080，见 httpserver.py 中runbasic的默认server_address=("0.0.0.0", 8080)），并通过httpserver.runsimple启动内置 HTTP 服务器；
• 若环境变量PORT已设置（如 Heroku 等 PaaS 平台），则以PORT的值作为监听端口。

也就是说，python hello.py与python hello.py 8000分别会把服务跑在 8080 与 8000 端口。内置服务器还会自动托管应用目录下的static/静态资源，开发阶段无需额外配置。

三、从 Hello World 到真实应用：文档树的四大主题

Hello World 只是起点。官方文档树（即 docs/index.rst 中toctree声明的七篇子文档）为继续深入提供了清晰的路线图，下面逐一导读其核心要点。

1. 用户输入处理（docs/input.rst）

任何 Web 应用都要读取客户端传来的参数。web.input()返回一个字典风格的web.storage对象，无论参数来自 URL 查询串（GET）还是表单体（POST/PUT），访问方式统一：

class Page(object): def GET(self): data = web.input() id = int(data.id) # 输入默认是字符串，按需转型 action = data.action ... class Login(object): def POST(self): data = web.input() name, password = data.name, data.password ...

要点有三：

• 未提供默认值时，若参数缺失会抛出KeyError；
• 更稳妥的做法是给web.input()传默认值：web.input(id=1, action='read')；
• 若同一参数名出现多次（如/page?id=1&id=2&id=3或多个同名 select），以[]作为该参数的默认值即可取到完整列表：data = web.input(id=[])，此时data.id是包含所有值的 list。

2. 数据库访问（docs/db.rst）

web.py 提供统一的数据库接口，对 PostgreSQL、MySQL、SQLite 一视同仁：

db = web.database(dbn='postgres', db='dbname', user='username', pw='password')

• dbn参数决定驱动：PostgreSQL 用postgres（需安装psycopg2）、MySQL 用mysql（需MySQLdb）、SQLite 用sqlite（标准库sqlite3，且不接收user/pw）；
• 多个数据库只需创建多个web.database()对象，各自独立使用；
• 连接关闭方式为db.ctx.db.close()。

该文档还详细覆盖了 select/insert/update/delete 等增删改查操作与事务、高级查询的写法，是后端开发的核心参考。

3. 模板系统（docs/templating.rst）

web.py 自带名为 templetor 的模板引擎，设计目标包括：模板外观清爽、最大限度复用 Python 语义、足够表达真实计算、可用于任何文本语言（不止 HTML/XML），并且实现要沙箱化、简单快速。变量替换的语法示例：

Look, a $string. Hark, an ${arbitrary + expression}. Gawk, a $dictionary[key].function('argument'). Cool, a $(limit)ing. Stop, \$money isn't evaluated.

$前缀做变量插值，${...}内嵌任意 Python 表达式，\$转义为字面美元符号；行尾反斜杠\可抑制换行。该文档还包含表达式、语句（for/if/def/code）、继承与布局等完整章节，对应实现可进一步阅读 web/template.py 与 web/contrib/template.py。

4. 部署上线（docs/deploying.rst）

开发环境的app.run()用的是内置服务器，生产环境则通常交给成熟 Web 服务器。官方文档提供两套主流方案：

FastCGI + lighttpd：web.py 通过flup库支持 FastCGI。应用文件需以#! /usr/bin/env python3开头并赋予可执行权限，再在 lighttpd 配置中声明fastcgi.server（指定 socket、bin-path、进程数与REAL_SCRIPT_NAME环境变量），并用url.rewrite-once把静态资源与其余请求分流——/static/交给 lighttpd 直接托管，其余全部转发给yourapp.py。

nginx + Gunicorn：更简单——web.py 应用天然是 WSGI 应用，只需显式取出 WSGI 函数：

import web ... app = web.application(urls, globals()) # 从 application 对象取出 wsgi 函数 wsgiapp = app.wsgifunc()

然后启动 Gunicorn：

gunicorn -w 4 -b 127.0.0.1:4000 yourapp:wsgiapp

即以前置 4 个 worker、监听本地 4000 端口的方式对外服务。

四、完整示例：把入门要素组合起来

把路由、输入、模板串起来，一个稍完整的应用大致如下（对应 Hello World 的扩展版）：

import web urls = ( "/", "index", "/hello/(.*)", "hello", ) app = web.application(urls, globals()) class index: def GET(self): return "Home page. Try /hello/world" class hello: def GET(self, name): return 'Hello, %s!' % name if __name__ == "__main__": app.run()

访问http://localhost:8080/hello/webpy将得到Hello, webpy!，路由正则的(.*)分组经由GET(self, name)传入。这与 tests/test_application.py 中do_iter类的写法同源——它甚至演示了GET方法返回生成器（yield）也能被正常处理，配合web.input()完成流式响应。

五、测试与后续学习路线

想验证你的 web.py 应用逻辑，可以直接在代码中使用应用对象的request方法做进程内请求测试，例如 application.py 文档字符串所示：

urls = ("/hello", "hello") app = web.application(urls, globals()) class hello: def GET(self): return "hello" app.request("/hello").data # b'hello'

这无需启动任何服务器即可断言路由与响应，正是仓库 tests/ 目录下各测试文件的通用手法。继续深入可依次阅读：

• docs/input.rst：用户输入全面处理；
• docs/db.rst：数据库访问与增删改查；
• docs/templating.rst：模板语法、布局与继承；
• docs/deploying.rst：FastCGI / Gunicorn 生产部署；
• docs/development.rst 与 docs/api.rst：开发指引与 API 参考（后者对应 web/ 包各模块的完整接口文档）。

从保存hello.py、python hello.py到浏览器看到 "Hello, world!"，web.py 用 8 行代码完成了框架入门，而上面的每一条文档路径都已为你的下一个真实项目铺好了路。

• 后端
• Web框架