InterSystems IRIS 2022.2 使用 JWT 保护 REST API 教程

一. 概述：REST 与 JWT

InterSystems IRIS 2022.2 引入了使用 JSON Web 令牌（JWT）对 REST API 进行身份验证的功能。通过设置访问令牌的过期时间，并限制密码在网络上传输的频率和范围，该功能显著提升了 API 的安全性。

本文将演示如何在 InterSystems IRIS 中创建一个模拟 REST API，并通过 JWT 保护其访问。

二. 什么是 REST？

REST（Representational State Transfer）是一种架构风格，允许程序与 Web 应用通信并访问其功能。REST API 通常基于 HTTP 协议，使用标准的 HTTP 方法（如 GET、POST、PUT、DELETE）对资源进行操作。

三. 什么是 JWT？

JSON Web 令牌（JWT）是一种紧凑且 URL 安全的方式，用于在双方之间传递声明。JWT 可进行数字签名、加密或两者兼备，从而确保数据完整性与安全性。JWT 在 REST API 身份验证中非常常见，能有效降低密码传输风险。

四. 生成 REST API 代码存根

InterSystems IRIS 提供便捷方法生成 REST API 代码存根。通过 OpenAPI 2.0 规范，可以快速生成基础 API 结构。生成的主要文件包括：

impl.cls：实现 API 的业务逻辑
disp.cls：处理 API 请求调度
spec.cls：定义 API 规范

实际开发中，大部分工作集中在 impl.cls 文件。

五. 实现 REST API

1. 定义对象模型

创建角色（Character）对象示例：

Class TTRPG.Character Extends %Persistent {
    Property Name As %String [Required];
    Property Race As %String;
    Property Class As %String;
    Property Level As %String;

    Index NameIndex On Name [IdKey];

    ClassMethod GetCharByName(Name As %String) As TTRPG.Character {
        Set Character = ##Class(TTRPG.Character).%OpenId(Name)
        Quit Character
    }
}

%Persistent 继承确保对象存储到数据库中，IdKey 保证角色名称唯一。

2. 创建角色 API 方法

ClassMethod PostCharacter(Name As %String, Class As %String, Race As %String, Level As %String) As %DynamicObject {
    Set results = {}
    Set char = ##Class(TTRPG.Character).%New()
    Set char.Name = Name
    Set char.Class = Class
    Set char.Race = Race
    Set char.Level = Level
    Set st = char.%Save()
    If st {
        Set charInfo = {}
        Set charInfo.Name = char.Name
        Set charInfo.Class = char.Class
        Set charInfo.Race = char.Race
        Set charInfo.Level = char.Level
        Set results.Character = charInfo
        Set results.Status = "Success"
    } Else {
        Set results.Status = "Error"
        Set results.Message = "无法创建角色"
    }
    Quit results
}

该方法接收角色属性参数，创建新对象并保存到数据库，返回操作结果。

3. 获取角色信息

按名称检索角色：

ClassMethod GetCharacterByName(charName As %String) As %DynamicObject {
    Set results = {}
    Set char = ##Class(TTRPG.Character).GetCharByName(charName)
    If char {
        Set charInfo = {}
        Set charInfo.Name = char.Name
        Set charInfo.Class = char.Class
        Set charInfo.Race = char.Race
        Set charInfo.Level = char.Level
        Set results.Character = charInfo
        Set results.Status = "Success"
    } Else {
        Set results.Status = "Error"
        Set results.Message = "未找到角色"
    }
    Quit results
}

4. 获取角色列表

ClassMethod GetCharacterList() As %DynamicObject {
    Set results = {}
    Set query = "SELECT Name, Class, Race, Level FROM TTRPG.Character"
    Set tStatement = ##Class(%SQL.Statement).%New()
    Set qstatus = tStatement.%Prepare(query)
    If qstatus '= 1 {
        Do ##Class(TTRPG.impl).%WriteResponse("错误：" _ $SYSTEM.Status.DisplayError(qstatus))
    }
    Set rset = tStatement.%Execute()
    Set characterList = []
    While rset.%Next() {
        Set charInfo = {}
        Set charInfo.Name = rset.Name
        Set charInfo.Class = rset.Class
        Set charInfo.Race = rset.Race
        Set charInfo.Level = rset.Level
        Do characterList.%Push(charInfo)
    }
    Set results.Status = "Success"
    Set results.TotalCount = rset.%ROWCOUNT
    Set results.CharacterList = characterList
    Quit results
}

六. 配置 IRIS 支持 JWT 身份验证

1. 配置 Web 应用程序

管理门户：系统管理 > 安全 > 应用程序 > Web应用程序
创建新 Web 应用程序，例如 /api/TTRPG/
选择 REST 单选按钮，并勾选 使用 JWT 身份认证
设置访问令牌超时时间（建议 3600 秒）和刷新令牌超时时间（建议 900 秒）

2. 配置 JWT 身份验证

管理门户：系统管理 > 安全 > 系统安全 > 身份验证/Web 会话选项
配置 JWT 颁发者和签名算法，例如颁发者设置为 InterSystems

七. 测试 REST API

1. 登录获取 JWT

通过 /login 端点发送请求：

{
    "user": "{YOURUSER}",
    "password": "{YOURPASSWORD}"
}

成功后返回 access_token。

2. 创建角色

POST /characters，请求头：

Authorization: Bearer {JWTValue}

3. 列出角色

GET /characters 获取所有角色列表。

4. 按名称检索角色

GET /characters/{charName} 获取单个角色信息。

八. 总结

本文演示了如何使用 InterSystems IRIS 创建 REST API，并通过 JWT 提高 API 安全性。该方法简化了身份验证，实现安全、可靠的 API 访问，适合企业级应用开发。

原文链接: https://community.intersystems.com/post/creating-rest-api-jwt-authentication-objectscript