湿空气物性计算 API

基于 FastAPI + CoolProp。给定任意 2 个状态参数，一次返回该状态点的全部湿空气物性，由调用方按需取用。

一、调用规则

  1. 请求方式：HTTP GET（单点）或 POST（批量），均返回 JSON。
  2. 查询参数名直接使用属性代码（见第三节），值为该属性的数值。
  3. 必须且只能提供 2 个状态参数（多 1 或少 1 → 400）。
  4. 压力 P 是可选参数，缺省 101325 Pa（标准大气压）；如需非标压（高原、加压舱等）显式传入即可。
  5. 响应中 state 字段包含该状态点的全部物性，前端自取所需字段。
  6. 温度统一 ℃，焓统一 kJ/(kg 干空气)，相对湿度 0~1（小数）。

URL 结构拆解

https://your-host/ha?T=25&R=0.5
主机 服务地址 路径 唯一计算端点 状态参数 任意 2 个 P 可选，缺省 101325 Pa

含义：在标准大气压、干球温度 25 ℃、相对湿度 50% 下，求湿空气全部物性。

二、单点调用 GET /ha

请求格式

GET /ha?<键1>=<值1>&<键2>=<值2>[&P=<Pa>]

响应格式

{
  "inputs":   { "<键1>": <值1>, "<键2>": <值2> },
  "pressure": { "P": 101325, "default": true },   // default=true 表示用了缺省值
  "state": {
    "T": ..., "Twb": ..., "Tdp": ...,
    "R": ..., "W": ...,
    "H": ..., "V": ...,
    "S": ..., "Y": ...
  }
}

state 中个别字段若 CoolProp 解算失败，会返回 null，不会阻断其他字段。

示例 1：标准大气下，已知 T + R

GET /ha?T=25&R=0.5
{
  "inputs":   { "T": 25, "R": 0.5 },
  "pressure": { "P": 101325, "default": true },
  "state": {
    "T":   25.00,
    "Twb": 17.89,
    "Tdp": 13.86,
    "R":   0.50,
    "W":   0.00993,
    "H":   50.42,
    "V":   0.8585,
    "S":   187.32,
    "Y":   0.01571
  }
}

示例 2：非标压（高原 80 kPa）

GET /ha?T=25&R=0.5&P=80000

响应中 pressure.default 为 false，表示已被显式覆盖。

示例 3：已知干球 + 湿球温度

GET /ha?T=30&Twb=22

示例 4：已知比焓 + 含湿量（焓湿图反查）

GET /ha?H=50&W=0.01

curl 调用

curl "https://your-host/ha?T=25&R=0.5"

三、参数（属性代码）含义

下表中同义代码任选其一。P 为可选项，其余均为状态参数。

代码物理含义单位 / 取值典型范围同义代码
P湿空气总压力（绝压，可选）Pa缺省 101325—
T干球温度℃−100 ~ 200Tdb
Twb湿球温度（绝热饱和温度）℃≤ TB
Tdp露点温度℃≤ TD
R相对湿度0 ~ 1（小数，非百分数）0.5 即 50%—
W含湿量（绝对湿度）kg 水 / kg 干空气0 ~ 0.05—
H湿空气比焓kJ / kg 干空气−50 ~ 200Hda
V比容m³ / kg 干空气≈ 0.7 ~ 1.0Vda
S比熵J / (kg·K)—Sda
Y水蒸气摩尔分数mol / mol0 ~ 1psi_w
💡 易错点

四、批量调用 POST /ha/batch

用于一次计算多个状态点（绘焓湿图、批量工况扫描等）。每个点独立解析、独立容错。

请求格式

POST /ha/batch
Content-Type: application/json

{
  "points": [
    { "T": 20, "R": 0.5 },
    { "T": 25, "R": 0.5 },
    { "T": 30, "R": 0.5, "P": 80000 }
  ]
}

响应格式

{
  "count": 3,
  "results": [
    {
      "index": 0,
      "inputs": { "T": 20, "R": 0.5 },
      "pressure": { "P": 101325, "default": true },
      "state": { "T": 20.00, "Twb": 13.78, ... },
      "status": "success"
    },
    ...
    {
      "index": 2,
      "inputs": { "T": 30, "R": 0.5 },
      "pressure": { "P": 80000, "default": false },
      "state": { ... },
      "status": "success"
    }
  ]
}
单个点失败不会中断整体请求；该点 status="error" 并附带 error 字段，其余点继续返回。

curl 调用

curl -X POST https://your-host/ha/batch \
  -H "Content-Type: application/json" \
  -d '{"points":[{"T":25,"R":0.5},{"T":30,"R":0.6}]}'

五、辅助接口

GET /ha/keys

返回服务端支持的全部状态参数代码、输出字段列表与单位说明，便于客户端动态构造表单。

GET /health

返回服务名与版本号，用于探活。

{ "status": "ok", "service": "CoolProp API", "version": "2.0.0" }

六、错误响应

// 状态参数个数不是 2
HTTP 400
{ "detail": "需要且仅需 2 个状态参数（除 P 之外），当前提供了 1 个" }

// 属性代码非法
HTTP 400
{ "detail": "存在无效的属性代码: ['XYZ']。有效代码见 /ha/keys" }

// 参数值不是合法数字
HTTP 400
{ "detail": "参数 T 的值 'abc' 不是有效的数字" }

// CoolProp 内部错误（输入组合不一致 / 越界等）
HTTP 500
{ "detail": "计算错误: ..." }

属性代码定义参考：CoolProp HumidAir 文档