Bottle：极简主义的Python微型Web框架
Bottle 是一个快速、简单且轻量级的 Python WSGI 微型 Web 框架。整个框架只有一个模块文件，并且除了 Python 标准库之外没有任何外部依赖。这让它的安装和分发极为方便，尤其适合用来构建小型 Web 应用、RESTful API 服务，或者作为入门者理解 Web 开发核心概念的练习框架。在其他重型框架可能显得臃肿的场景下，Bottle 用最少的代码和清晰的设计，让开发者可以专注于逻辑本身。
一、安装与快速入门
安装 Bottle 只需要一行命令，所有现代 Python 环境都支持：
pip install bottle
安装完成后，我们可以通过导入关键组件来验证是否成功。Bottle 最核心的两个函数是route和run，它们负责路由注册和启动内置开发服务器。下面是一个最基础的示例，它在/hello路径上返回一段简单的文本：
from bottle import route, run
@route('/hello')
def hello():
return "Hello World!"
if __name__ == '__main__':
run(host='localhost', port=8080)运行这段脚本后，控制台会提示服务已经启动。在浏览器中访问http://localhost:8080/hello，就能看到 “Hello World!” 字样。这里的@route装饰器将 URL 路径与视图函数绑定，run函数启动了一个基于wsgiref的开发服务器，默认监听本地localhost:8080。这个服务器仅适用于开发和调试，不适合生产环境，但它能让开发者快速看到效果。
除了静态路径，Bottle 还支持动态路由。例如，我们可以定义一个接受用户名参数的问候接口：
from bottle import route
@route('/user/<name>')
def greet(name='Guest'):
return f'Hello, {name}!'访问/user/John就会返回 “Hello, John!”。在路径中，<name>表示一个动态片段，它会作为参数传递给视图函数。为了更精确地控制参数类型，Bottle 支持过滤器，例如<id:int>只匹配数字，<path:path>可以匹配包含斜杠的完整路径。这些内置机制让路由定义既简单又灵活，不需要额外的正则表达式就能应对大部分场景。
二、核心概念详解
1. 路由与HTTP方法
路由不仅可以根据URL路径分发请求，还能区分不同的HTTP方法。Bottle 提供了与@route等价的快捷装饰器，如@get、@post、@put、@delete等，让代码意图更加清晰。以下示例展示了如何用@get显示一个HTML表单，用@post处理提交的数据：
from bottle import get, post, request
@get('/form')
def show_form():
return '''<form action="/submit" method="post">
<input name="name" type="text" />
<button type="submit">Submit</button>
</form>'''
@post('/submit')
def submit():
name = request.forms.get('name')
return f'Submitted name: {name}'上面代码中，@get('/form')处理GET请求，返回一个包含输入框和提交按钮的简单表单。当用户填写名字并点击提交时，浏览器会向/submit发送POST请求，@post('/submit')装饰的函数负责接收并处理。值得注意的是，在字符串中我们直接书写了原始HTML，其中的<form>、<input>等标签被原样返回，这是小型应用中常见的做法。
Bottle 还允许在一个路由上同时指定多个方法，只需在@route中传入method参数，例如@route('/login', method=['GET', 'POST'])。这样可以在同一个视图函数内部通过request.method判断请求类型，从而区分展示页面和处理逻辑，代码更为紧凑。
2. 请求对象（request）
Bottle 使用一个线程局部安全的全局request对象来封装所有客户端请求信息。无论是查询字符串、POST表单、上传文件还是Cookie，都可以通过简单的属性访问。处理查询参数时，可以直接通过点号获取：
from bottle import route, request
@route('/search')
def search():
keyword = request.query.get('q', '')
return f'Searching for: {keyword}'访问/search?q=bottle，视图函数就能读取到keyword的值。这种属性访问方式其实是MultiDict的语法糖，支持get、getall等方法，非常直观。
对于POST请求提交的表单数据，使用request.forms即可，它同样是MultiDict类型。如果遇到文件上传，则通过request.files获取：
@post('/upload')
def do_upload():
upload = request.files.get('file')
if upload:
upload.save('/tmp/' + upload.filename)
return 'File saved.'
return 'No file uploaded.'这里的request.files.get('file')返回的是一个FileUpload对象，它包含了文件名、内容以及save()方法，极大地方便了文件处理逻辑。此外，request.headers、request.cookies、request.json等属性也能获取更多请求细节，无需额外解析。
3. 响应对象（response）与JSON处理
Bottle 视图函数的返回值直接作为响应体。如果返回一个字符串，默认的Content-Type是text/html。但很多API接口需要返回JSON数据。Bottle提供了一个便捷特性：当返回值为字典或列表时，框架会自动将其转换为JSON字符串，并将Content-Type设置为application/json。
from bottle import route, response
@route('/api/data')
def api_data():
response.content_type = 'application/json'
return {'status': 'success', 'data': [1, 2, 3]}虽然手动设置response.content_type不是必须的，但显式声明可以让意图更清晰。此外，还可以通过response.status修改HTTP状态码，例如response.status = 201表示创建成功。如果想返回一个完全自定义的响应，可以使用HTTPResponse对象或者static_file等辅助函数，让响应控制更加精细。
三、模板引擎
Bottle 内建了一个名为 SimpleTemplate 的轻量级模板引擎，它允许在HTML中直接嵌入Python代码，语法简洁且执行速度快。要使用模板，可以调用template函数，传入模板文件名和上下文变量。例如，创建一个名为hello_template.tpl的模板文件：
Hello {{name}}!
% if name == 'Admin':
Welcome back, administrator!
% else:
Welcome to our site.
% end在这个模板中，{{name}}用于输出变量值，%开头的行表示控制语句，如条件判断和循环，而缩进决定了代码块的边界。在else分支中，缩进内容会被正确识别。最终的视图函数可以这样写：
from bottle import route, template
@route('/hello/<name>')
def index(name):
return template('hello_template.tpl', name=name)除了文件模板，Bottle 也支持直接传入字符串作为模板内容，例如template('Hello {{name}}!', name=name)，这种方式适合非常简单的动态片段。SimpleTemplate 还提供了循环、包含子模板、定义块等功能，足以覆盖绝大多数小型项目的需求。不过，当项目变得复杂时，也可以轻松替换为 Jinja2 等第三方模板引擎，Bottle 通过插件机制支持这种扩展。
四、运行与部署
Bottle 自带的开发服务器基于标准库的wsgiref，是一个单线程、单进程的模式，每次只能处理一个请求。因此，它只适合在开发阶段快速迭代。一旦需要部署到生产环境，就必须使用真正的WSGI服务器。常见的生产级WSGI服务器有 Gunicorn、uWSGI 以及 Waitress 等，它们能够提供多进程、多线程的处理能力，显著提升并发性能。
以 Gunicorn 为例，首先安装它：
pip install gunicorn
然后对 Bottle 应用稍作调整，不再调用内置的run()，而是暴露一个应用实例：
from bottle import Bottle
app = Bottle()
@app.route('/')
def index():
return "Production Ready!"保存为myapp.py，接着执行gunicorn myapp:app，Gunicorn 会接管该应用，默认监听127.0.0.1:8000。通过调整 Gunicorn 的命令行参数，可以设置工作进程数、绑定地址、日志级别等。这种方式让 Bottle 应用获得了稳定的生产服务能力，而框架本身依然保持小巧。
另外，由于 Bottle 是一个标准的 WSGI 应用，它几乎可以运行在任何支持 WSGI 的服务器上，包括 Apache 的 mod_wsgi 模块、Nginx 配合 uWSGI 等，甚至可以直接部署在云平台的无服务器函数中，体现了微型框架的极强适应性。
五、总结
Bottle 的核心优势是“零依赖”和极低的学习曲线。整个框架只有一个文件，接口设计非常直观，让初学者可以快速理解请求处理、路由映射、模板渲染等Web开发基础。对于构建微服务、小型API、物联网后端或自动化工具的内部管理界面，Bottle 能够用最少的代码完成任务，避免过度设计。
当然，Bottle 的简约也意味着它不具备大型框架那样的组件生态，例如它没有自带的ORM、内置的表单验证或国际化支持。当项目规模逐步扩大，确实需要这些重量级功能时，从 Bottle 迁移到 Flask 或 Django 是一件相对容易的事，因为它们的路由思路和WSGI思想是相通的。在学习或原型阶段，选择 Bottle 可以让开发者聚焦核心逻辑，而不会被框架本身所累。
Bottle 这种小巧而强大的特性，让它至今仍受到许多开发者的喜爱，尤其适合那些崇尚KISS（Keep It Simple, Stupid）原则的项目。
Python Bottle框架WSGI路由处理SimpleTemplate模板Gunicorn部署修改时间：2026-08-02 22:45:41