response — 响应对象

response 模块封装了 HTTP 响应操作，用于在接口脚本中返回各种格式的响应数据。

引入方式

response 为全局对象，无需 require，可直接使用。

JSON 响应

Json — 返回 JSON

response.Json({
    code: 200,
    msg: "success",
    data: { name: "张三" }
})

Success — 返回成功响应

response.Success({ name: "张三" })

Error — 返回错误响应

response.Error("参数错误")

Page — 分页响应

response.Page(list, total, page, pageSize)

模板渲染

模板引擎基于 pongo2（Django 语法）：变量用 {{ }} 输出，逻辑用 {% %} 标签，注释用 {# #}。模板中的变量直接使用 data 对象的字段名。

Template — 渲染 HTML 模板

Template(path, data) 读取模板文件（相对服务进程工作目录）渲染后返回 HTML。data 为对象时，其字段直接作为模板顶层变量。

接口脚本：

var users = db.Select("SELECT name, dept, salary, status FROM users")

response.Template("templates/report.html", {
    title: "月度报表",
    month: "2026-09",
    company: "示例科技有限公司",
    users: users,
    totalSalary: users.reduce((s, u) => s + Number(u.salary), 0),
    generatedAt: time.Now()
})

templates/report.html：

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>{{ title }}</title>
    <style>
        body { font-family: sans-serif; margin: 24px; }
        table { border-collapse: collapse; width: 100%; }
        th, td { border: 1px solid #ddd; padding: 8px; text-align: left; }
        th { background: #f5f5f5; }
    </style>
</head>
<body>
    {# 单行注释：不会输出到结果 #}
    <h1>{{ title }}（{{ month }}）</h1>
    <p>{{ company }} · 共 {{ users|length }} 人 · 生成时间：{{ generatedAt }}</p>

    {% if users %}
    <table>
        <tr>
            <th>#</th><th>姓名</th><th>部门</th><th>薪资</th><th>状态</th>
        </tr>
        {% for u in users %}
        <tr>
            <td>{{ forloop.counter }}</td>
            <td>
                {{ u.name }}
                {% if forloop.first %}<small>（首行）</small>{% endif %}
            </td>
            <td>{{ u.dept|default:"未分配" }}</td>
            <td>{{ u.salary|floatformat:2 }}</td>
            <td>
                {% if u.status == "active" %}
                    <span style="color:green">在职</span>
                {% elif u.status == "leave" %}
                    <span style="color:orange">休假</span>
                {% else %}
                    <span style="color:red">离职</span>
                {% endif %}
            </td>
        </tr>
        {% endfor %}
        <tr>
            <td colspan="3"><b>合计</b></td>
            <td>{{ totalSalary|floatformat:2 }}</td>
            <td></td>
        </tr>
    </table>
    {% else %}
    <p>本月暂无数据。</p>
    {% endif %}
</body>
</html>

常用语法速查：

语法	说明
{{ title }} / {{ u.name }}	输出变量 / 嵌套属性
{{ u.dept|default:"-" }}	过滤器：为空时的默认值
{{ u.salary|floatformat:2 }}	过滤器：保留 2 位小数
{{ users|length }}	过滤器：数组长度
{% if a == 1 and b != "x" %}…{% elif %}…{% else %}…{% endif %}	条件（支持 and/or/not、==/!=/>/</>=/<=/in）
{% for u in users %}…{% endfor %}	循环
forloop.counter / forloop.counter0	循环计数（1 起 / 0 起）
forloop.first / forloop.last	是否首行 / 末行
{% for %}…{% empty %}…{% endfor %}	空数组时的分支
{% for o in u.orders %}	循环可嵌套，访问嵌套属性
{# 注释 #} / {% comment %}…{% endcomment %}	注释（不输出）

Text — 渲染文本模板

与 Template 相同的 pongo2 语法，但模板内容直接写在字符串里，返回 text/plain。

response.Text("您好，{{ name }}，本月报表共 {{ count }} 条", {
    name: "张三",
    count: 12
})

文件响应

File — 发送文件

response.File("/path/to/file.pdf")

Download — 文件下载

response.Download("/path/to/file.zip", "报表.zip")

格式化响应

XML

response.XML({ name: "张三" })

HTML

response.HTML("<h1>Hello World</h1>")

CSV

response.Csv(csvBytes, "data.csv")

Excel

response.Excel(excelBytes, "report.xlsx")

PDF

response.PDF(pdfBytes)

状态码响应

方法	说明
response.NotFound("未找到")	404 响应
response.Unauthorized("未授权")	401 响应
response.Forbidden("禁止访问")	403 响应
response.InternalError("服务器错误")	500 响应
response.Created(data)	201 创建成功
response.NoContent()	204 无内容

重定向

response.Redirect("https://example.com")
response.RedirectPermanent("https://example.com")
response.RedirectWithCode("https://example.com", 302)

Cookie 操作

SetCookie — 设置 Cookie

response.SetCookie("token", "abc123", 3600, "/", "", false, true)

参数	说明
name	Cookie 名称
value	Cookie 值
maxAge	过期时间（秒）
path	路径
domain	域名
secure	是否仅 HTTPS
httpOnly	是否禁止 JS 访问

DeleteCookie — 删除 Cookie

response.DeleteCookie("token")

响应头设置

response.SetHeader("X-Custom-Header", "value")
response.SetHeaders({
    "X-Request-Id": "12345",
    "X-Server": "SSS-RUN"
})
response.SetStatusCode(200)

SSE（Server-Sent Events）

response.SSE("message", "Hello World")

CORS 设置

response.CORS("*", ["GET", "POST"], ["Content-Type"], true)

完整示例

// 返回 JSON 数据
var users = db.Select("SELECT * FROM users")
response.Json({
    code: 200,
    msg: "success",
    data: users
})

// 返回分页数据
var page = db.Page(1, 20, "SELECT * FROM users")
response.Page(page.list, page.total, page.page, page.pageSize)

// 返回错误
if (!request.Has("id")) {
    response.Error("缺少 id 参数")
    return
}

// 文件下载
response.Download("/data/report.xlsx", "报表.xlsx")

// 设置 Cookie 后返回
response.SetCookie("token", token, 86400, "/", "", false, true)
response.Success({ username: "admin" })