ActiveResource.js: JSON API를 위한 강력한 JavaScript SDK를 빠르게 구축

귀사에서 API를 출시했으며 이제 API를 중심으로 사용자 커뮤니티를 구축하려고 합니다. API가 제공하는 서비스를 통해 고객이 모든 것을 직접 작성하는 대신 웹 애플리케이션을 더 쉽게 구축할 수 있기 때문에 대부분의 고객이 JavaScript로 작업할 것이라는 사실을 알고 있습니다. Twilio가 이에 대한 좋은 예입니다.

또한 RESTful API가 간단할 수 있지만 사용자는 자신을 위해 모든 힘든 작업을 수행할 JavaScript 패키지를 사용하고 싶어할 것입니다. 그들은 API를 배우고 스스로 필요한 각 요청을 작성하는 것을 원하지 않을 것입니다.

따라서 API를 중심으로 라이브러리를 구축하고 있습니다. 또는 자체 내부 API와 상호 작용하는 웹 애플리케이션을 위한 상태 관리 시스템을 작성하고 있을 수도 있습니다.

어느 쪽이든, API 리소스 중 하나를 CRUD할 때마다 반복하거나 더 나쁜 경우 해당 리소스와 관련된 리소스를 CRUD하고 싶지 않습니다. 이것은 장기적으로 성장하는 SDK를 관리하는 데 좋지 않으며 시간을 잘 사용하지도 않습니다.

대신 API와 상호 작용하기 위한 JavaScript ORM 시스템인 ActiveResource.js를 사용할 수 있습니다. 가능한 한 적은 수의 라인으로 JavaScript SDK를 생성하는 프로젝트의 요구 사항을 충족하기 위해 만들었습니다. 이를 통해 우리와 개발자 커뮤니티의 효율성을 극대화할 수 있었습니다.

이것은 Ruby on Rails의 간단한 ActiveRecord ORM의 원리를 기반으로 합니다.

자바스크립트 SDK 원칙

ActiveResource.js의 디자인을 안내한 두 가지 Ruby on Rails 아이디어가 있습니다.

1. "구성에 대한 규칙": API 끝점의 특성에 대해 몇 가지 가정을 합니다. 예를 들어 Product 리소스가 있는 경우 /products 엔드포인트에 해당합니다. 그렇게 하면 API에 대한 각 SDK 요청을 반복적으로 구성하는 데 시간이 소모되지 않습니다. 개발자는 복잡한 CRUD 쿼리가 포함된 새 API 리소스를 몇 시간이 아닌 몇 분 만에 성장하는 SDK에 추가할 수 있습니다.
2. "아름다운 코드를 높이세요." Rails의 창시자인 DHH가 가장 잘 말했습니다. 아름다운 코드는 그 자체로 대단한 것이 있습니다. ActiveResource.js는 때때로 못생긴 요청을 아름다운 외관으로 포장합니다. 필터와 페이지 매김을 추가하고 GET 요청에 대한 관계에 중첩된 관계를 포함하기 위해 더 이상 사용자 지정 코드를 작성할 필요가 없습니다. 또한 개체의 속성을 변경하고 업데이트를 위해 서버로 보내는 POST 및 PATCH 요청을 구성할 필요도 없습니다. 대신 ActiveResource에서 메서드를 호출하기만 하면 됩니다. 원하는 요청을 얻기 위해 더 이상 JSON을 가지고 놀지 않고 다음 요청을 위해 다시 수행하면 됩니다.

시작하기 전에

이 글을 쓰는 시점에서 ActiveResource.js는 JSON:API 표준에 따라 작성된 API에서만 작동한다는 점에 유의해야 합니다.

JSON:API에 익숙하지 않고 따라하고 싶다면 JSON:API 서버를 만들기 위한 좋은 라이브러리가 많이 있습니다.

즉, ActiveResource.js는 특정 API 표준에 대한 래퍼라기보다 DSL에 가깝습니다. API와 상호 작용하는 데 사용하는 인터페이스를 확장할 수 있으므로 향후 기사에서 사용자 지정 API와 함께 ActiveResource.js를 사용하는 방법을 다룰 수 있습니다.

설정하기

시작하려면 프로젝트에 active-resource 를 설치하세요.

 yarn add active-resource

첫 번째 단계는 API용 ResourceLibrary 를 만드는 것입니다. 내 모든 ActiveResource 를 src/resources 폴더에 넣겠습니다.

 // /src/resources/library.js import { createResourceLibrary } from 'active-resource'; const library = createResourceLibrary('http://example.com/api/v1'); export default library;

createResourceLibrary 에 필요한 유일한 매개변수는 API의 루트 URL입니다.

우리가 만들 것

콘텐츠 관리 시스템 API용 JavaScript SDK 라이브러리를 만들 것입니다. 즉, 사용자, 게시물, 댓글 및 알림이 있습니다.

사용자는 게시물을 읽고, 만들고, 편집할 수 있습니다. 댓글(게시물 또는 다른 댓글에 대한)을 읽고 추가하고 삭제하고 새 게시물 및 댓글에 대한 알림을 받습니다.

뷰(React, Angular 등) 또는 상태(Redux 등)를 관리하기 위해 특정 라이브러리를 사용하지 않고 ActiveResource 를 통해 API와만 상호 작용하도록 자습서를 추상화합니다.

첫 번째 리소스: 사용자

CMS의 사용자를 관리하기 위한 User 리소스를 만드는 것으로 시작하겠습니다.

먼저 몇 가지 attributes 이 있는 User 리소스 클래스를 만듭니다.

 // /src/resources/User.js import library from './library'; class User extends library.Base { static define() { this.attributes('email', 'userName', 'admin'); } } export default library.createResource(User);

일단 사용자가 이메일과 비밀번호를 제출하면 액세스 토큰과 사용자 ID를 반환하는 인증 엔드포인트가 있다고 가정해 보겠습니다. 이 끝점은 일부 함수 requestToken 에 의해 관리됩니다. 인증된 사용자 ID를 받으면 모든 사용자 데이터를 로드하려고 합니다.

 import library from '/src/resources/library'; import User from '/src/resources/User'; async function authenticate(email, password) { let [accessToken, userId] = requestToken(email, password); library.headers = { Authorization: 'Bearer ' + accessToken }; return await User.find(userId); }

내 ResourceLibrary 의 모든 향후 요청이 승인되도록 accessToken 이 있는 Authorization 헤더를 갖도록 library.headers 를 설정했습니다.

이후 섹션에서는 사용자를 인증하고 User 리소스 클래스만 사용하여 액세스 토큰을 설정하는 방법에 대해 설명합니다.

authenticate 의 마지막 단계는 User.find(id) 에 대한 요청입니다. 이것은 /api/v1/users/:id 에 대한 요청을 만들고 응답은 다음과 같을 것입니다:

 { "data": { "type": "users", "id": "1", "attributes": { "email": "[email protected]", "user_name": "user1", "admin": false } } }

authenticate 의 응답은 User 클래스의 인스턴스가 됩니다. 애플리케이션의 어딘가에 표시하려는 경우 여기에서 인증된 사용자의 다양한 속성에 액세스할 수 있습니다.

 let user = authenticate(email, password); console.log(user.id) // '1' console.log(user.userName) // user1 console.log(user.email) // [email protected] console.log(user.attributes()) /* { email: '[email protected]', userName: 'user1', admin: false } */

각 속성 이름은 JavaScript의 일반적인 표준에 맞게 camelCased가 됩니다. 각각을 user 객체의 속성으로 직접 가져 user.attributes() 를 호출하여 모든 속성을 가져올 수 있습니다.

리소스 인덱스 추가

알림과 같이 User 클래스와 관련된 리소스를 더 추가하기 전에 모든 리소스를 인덱싱할 src/resources/index.js 파일을 추가해야 합니다. 여기에는 두 가지 이점이 있습니다.

1. 여러 import 문을 사용하는 대신 하나의 import 문에서 여러 리소스에 대한 src/resources 를 구조화할 수 있도록 하여 가져오기를 정리합니다.
2. ActiveResource.js가 관계를 구축하는 데 필요한 각각에 대해 library.createResource 를 호출하여 생성할 ResourceLibrary 의 모든 리소스를 초기화합니다.

 // /src/resources/index.js import User from './User'; export { User };

관련 리소스 추가

이제 User 에 대한 관련 리소스인 Notification 을 생성해 보겠습니다. 먼저 User 클래스에 belongsTo Notification 클래스를 만듭니다.

 // /src/resources/Notification.js import library from './library'; class Notification extends library.Base { static define() { this.belongsTo('user'); } } export default library.createResource(Notification);

그런 다음 리소스 인덱스에 추가합니다.

 // /src/resources/index.js import Notification from './Notification'; import User from './User'; export { Notification, User };

그런 다음 알림을 User 클래스와 연결합니다.

 // /src/resources/User.js class User extends library.Base { static define() { /* ... */ this.hasMany('notifications'); } }

이제 사용자가 authenticate 에서 돌아오면 모든 알림을 로드하고 표시할 수 있습니다.

 let notifications = await user.notifications().load(); console.log(notifications.map(notification => notification.message));

인증된 사용자에 대한 원래 요청에 알림을 포함할 수도 있습니다.

 async function authenticate(email, password) { /* ... */ return await User.includes('notifications').find(userId); }

이것은 DSL에서 사용할 수 있는 많은 옵션 중 하나입니다.

DSL 검토

지금까지 작성한 코드에서 이미 요청할 수 있는 내용을 살펴보겠습니다.

사용자 모음 또는 단일 사용자를 쿼리할 수 있습니다.

 let users = await User.all(); let user = await User.first(); user = await User.last(); user = await User.find('1'); user = await User.findBy({ userName: 'user1' });

연결 가능한 관계형 메서드를 사용하여 쿼리를 수정할 수 있습니다.

 // Query and iterate over all users User.each((user) => console.log(user)); // Include related resources let users = await User.includes('notifications').all(); // Only respond with user emails as the attributes users = await User.select('email').all(); // Order users by attribute users = await User.order({ email: 'desc' }).all(); // Paginate users let usersPage = await User.page(2).perPage(5).all(); // Filter users by attribute users = await User.where({ admin: true }).all(); users = await User .includes('notifications') .select('email', { notifications: ['message', 'createdAt'] }) .order({ email: 'desc' }) .where({ admin: false }) .perPage(10) .page(3) .all(); let user = await User .includes('notification') .select('email') .first();

연결된 수식어를 얼마든지 사용하여 쿼리를 작성할 수 있으며 .all() , .first() , .last() 또는 .each() 로 쿼리를 종료할 수 있습니다.

로컬에서 사용자를 만들거나 서버에서 만들 수 있습니다.

 let user = User.build(attributes); user = await User.create(attributes);

지속 사용자가 있으면 변경 사항을 보내 서버에 저장할 수 있습니다.

 user.email = '[email protected]'; await user.save(); /* or */ await user.update({ email: '[email protected]' });

서버에서 삭제할 수도 있습니다.

 await user.destroy();

이 기본 DSL은 튜토리얼의 나머지 부분에서 설명하겠지만 관련 리소스로도 확장됩니다. 이제 ActiveResource.js를 나머지 CMS(게시물 및 댓글) 생성에 빠르게 적용할 수 있습니다.

게시물 작성

Post 에 대한 리소스 클래스를 만들고 이를 User 클래스와 연결합니다.

 // /src/resources/Post.js import library from './library'; class Post extends library.Base { static define() { this.belongsTo('user'); } } export default library.createResource(Post);

 // /src/resources/User.js class User extends library.Base { static define() { /* ... */ this.hasMany('notifications'); this.hasMany('posts'); } }

리소스 인덱스에도 Post 를 추가합니다.

 // /src/resources/index.js import Notification from './Notification'; import Post from './Post'; import User from './User'; export { Notification, Post, User };

그런 다음 사용자가 게시물을 만들고 편집할 수 있도록 Post 리소스를 양식에 연결합니다. 사용자가 새 게시물을 작성하기 위해 양식을 처음 방문할 때 Post 리소스가 빌드되고 양식이 변경될 때마다 변경 사항을 Post 에 적용합니다.

 import Post from '/src/resources/Post'; let post = Post.build({ user: authenticatedUser }); onChange = (event) => { post.content = event.target.value; };

그런 다음 양식에 onSubmit 콜백을 추가하여 게시물을 서버에 저장하고 저장 시도가 실패하면 오류를 처리합니다.

 onSubmit = async () => { try { await post.save(); /* successful, redirect to edit post form */ } catch { post.errors().each((field, error) => { console.log(field, error.message) }); } }

게시물 편집

게시물이 저장되면 서버의 리소스로 API에 연결됩니다. persisted 를 호출하여 리소스가 서버에서 지속되는지 여부를 알 수 있습니다.

 if (post.persisted()) { /* post is on server */ }

지속형 리소스의 경우 ActiveResource.js는 더티 속성을 지원하므로 리소스의 속성이 서버의 값에서 변경되었는지 확인할 수 있습니다.

지속형 리소스에 대해 save() 를 호출하면 리소스의 전체 속성 및 관계 집합을 불필요하게 서버에 제출하는 대신 리소스에 대한 변경 사항만 포함하는 PATCH 요청을 만듭니다.

attributes 선언을 사용하여 추적된 속성을 리소스에 추가할 수 있습니다. post.content 의 변경 사항을 추적해 보겠습니다.

 // /src/resources/Post.js class Post extends library.Base { static define() { this.attributes('content'); /* ... */ } }

이제 서버 지속 게시물로 게시물을 편집할 수 있으며 제출 버튼을 클릭하면 변경 사항을 서버에 저장합니다. 아직 변경 사항이 없으면 제출 버튼을 비활성화할 수도 있습니다.

 onEdit = (event) => { post.content = event.target.value; } onSubmit = async () => { try { await post.save(); } catch { /* display edit errors */ } } disableSubmitButton = () => { return !post.changed(); }

게시물과 관련된 사용자를 변경하려는 경우 post.user() 와 같은 단일 관계를 관리하는 메서드가 있습니다.

 await post.updateUser(user);

이것은 다음과 동일합니다.

 await post.update({ user });

댓글 리소스

이제 리소스 클래스 Comment 를 만들고 이를 Post 에 연결합니다. 댓글은 게시물 또는 다른 댓글에 대한 응답이 될 수 있으므로 댓글에 대한 관련 리소스는 다형성이어야 한다는 요구 사항을 기억하십시오.

 // /src/resources/Comment.js import library from './library'; class Comment extends library.Base { static define() { this.attributes('content'); this.belongsTo('resource', { polymorphic: true, inverseOf: 'replies' }); this.belongsTo('user'); this.hasMany('replies', { as: 'resource', className: 'Comment', inverseOf: 'resource' }); } } export default library.createResource(Comment);

/src/resources/index.js 에도 Comment 을 추가해야 합니다.

Post 클래스에도 한 줄을 추가해야 합니다.

 // /src/resources/Post.js class Post extends library.Base { static define() { /* ... */ this.hasMany('replies', { as: 'resource', className: 'Comment', inverseOf: 'resource' }); } }

replies 을 위해 hasMany 정의에 전달된 inverseOf 옵션은 관계가 resource 에 대한 다형성 belongsTo 정의의 역임을 나타냅니다. 관계의 inverseOf 속성은 관계 간의 연산을 수행할 때 자주 사용됩니다. 일반적으로 이 속성은 클래스 이름을 통해 자동으로 결정되지만 다형성 관계는 여러 클래스 중 하나일 수 있으므로 다형성 관계가 일반 관계와 동일한 기능을 갖기 위해서는 inverseOf 옵션을 직접 정의해야 합니다.

게시물 댓글 관리

리소스에 적용되는 동일한 DSL은 관련 리소스 관리에도 적용됩니다. 이제 게시물과 댓글 간의 관계를 설정했으므로 이 관계를 관리할 수 있는 여러 가지 방법이 있습니다.

게시물에 새 댓글을 추가할 수 있습니다.

 onSubmitComment = async (event) => { let comment = await post.replies().create({ content: event.target.value, user: user }); }

댓글에 답글을 추가할 수 있습니다.

 onSubmitReply = async (event) => { let reply = await comment.replies().create({ content: event.target.value, user: user }); }

댓글을 수정할 수 있습니다.

 onEditComment = async (event) => { await comment.update({ content: event.target.value }); }

게시물에서 댓글을 삭제할 수 있습니다.

 onDeleteComment = async (comment) => { await post.replies().delete(comment); }

게시물 및 댓글 표시

SDK를 사용하여 페이지가 매겨진 게시물 목록을 표시할 수 있으며 게시물을 클릭하면 게시물이 모든 댓글과 함께 새 페이지에 로드됩니다.

 import { Post } from '/src/resources'; let postsPage = await Post .order({ createdAt: 'desc' }) .select('content') .perPage(10) .all();

위의 쿼리는 가장 최근 게시물 10개를 검색하고 최적화를 위해 로드되는 유일한 속성은 content 입니다.

사용자가 게시물의 다음 페이지로 이동하기 위해 버튼을 클릭하면 변경 핸들러가 다음 페이지를 검색합니다. 다음 페이지가 없으면 여기에서도 버튼을 비활성화합니다.

 onClickNextPage = async () => { postsPage = await postsPage.nextPage(); if (!postsPage.hasNextPage()) { /* disable next page button */ } };

게시물에 대한 링크를 클릭하면 댓글(답글이라고 함)과 해당 답변에 대한 답변을 포함하여 모든 데이터가 포함된 게시물을 로드하고 표시하여 새 페이지를 엽니다.

 import { Post } from '/src/resources'; onClick = async (postId) => { let post = await Post.includes({ replies: 'replies' }).find(postId); console.log(post.content, post.createdAt); post.replies().target().each(comment => { console.log( comment.content, comment.replies.target().map(reply => reply.content).toArray() ); }); }

post.replies() 와 같은 hasMany 관계에서 .target() 을 호출하면 로컬에서 로드 및 저장된 주석의 ActiveResource.Collection 이 반환됩니다.

post.replies().target().first() 가 로드된 첫 번째 주석을 반환하기 때문에 이 구분은 중요합니다. 대조적으로, post.replies().first() 는 GET /api/v1/posts/:id/replies 에서 요청된 하나의 주석에 대한 약속을 반환합니다.

게시물 자체에 대한 요청과 별도로 게시물에 대한 응답을 요청할 수도 있으므로 쿼리를 수정할 수 있습니다. 리소스 자체를 쿼리할 때와 마찬가지로 hasMany 관계를 쿼리할 때 order , select , perPage , where , includes , page 와 같은 수정자를 연결할 수 있습니다.

 import { Post } from '/src/resources'; onClick = async (postId) => { let post = await Post.find(postId); let userComments = await post.replies().where({ user: user }).perPage(3).all(); console.log('Your comments:', userComments.map(comment => comment.content).toArray()); }

요청 후 리소스 수정

때때로 서버에서 데이터를 가져와 사용하기 전에 수정하고 싶을 때가 있습니다. 예를 들어, post.createdAt 를 moment() 객체로 래핑하여 게시물이 생성된 시기에 대해 사용자에게 친숙한 날짜/시간을 표시할 수 있습니다.

 // /src/resources/Post.js import moment from 'moment'; class Post extends library.Base { static define() { /* ... */ this.afterRequest(function() { this.createdAt = moment(this.createdAt); }); } }

불변성

불변 개체를 선호하는 상태 관리 시스템으로 작업하는 경우 리소스 라이브러리를 구성하여 ActiveResource.js의 모든 동작을 불변으로 만들 수 있습니다.

 // /src/resources/library.js import { createResourceLibrary } from 'active-resource'; const library = createResourceLibrary( 'http://example.com/api/v1', { immutable: true } ); export default library;

Circling Back: 인증 시스템 연결

마무리하기 위해 사용자 인증 시스템을 User ActiveResource 에 통합하는 방법을 보여 드리겠습니다.

토큰 인증 시스템을 API 엔드포인트 /api/v1/tokens 로 이동하십시오. 사용자의 이메일과 비밀번호가 이 끝점으로 전송되면 인증된 사용자의 데이터와 인증 토큰이 응답으로 전송됩니다.

User 에 속하는 Token 리소스 클래스를 만듭니다.

 // /src/resources/Token.js import library from './library'; class Token extends library.Base { static define() { this.belongsTo('user'); } } export default library.createResource(Token);

/src/resources/index.js 에 Token 을 추가합니다.

그런 다음 정적 authenticate 를 User 리소스 클래스에 추가하고 User 를 Token 에 연결합니다.

 // /src/resources/User.js import library from './library'; import Token from './Token'; class User { static define() { /* ... */ this.hasOne('token'); } static async authenticate(email, password) { let user = this.includes('token').build({ email, password }); let authUser = await this.interface().post(Token.links().related, user); let token = authUser.token(); library.headers = { Authorization: 'Bearer ' + token.id }; return authUser; } }

이 메서드는 resourceLibrary.interface() 를 사용하며 이 경우 JSON:API 인터페이스를 사용하여 사용자를 /api/v1/tokens 로 보냅니다. 이것은 유효합니다. JSON:API의 끝점은 게시된 유일한 유형이 이름을 따서 명명된 유형일 필요가 없습니다. 따라서 요청은 다음과 같습니다.

 { "data": { "type": "users", "attributes": { "email": "[email protected]", "password": "password" } } }

응답은 인증 토큰이 포함된 인증된 사용자입니다.

 { "data": { "type": "users", "id": "1", "attributes": { "email": "[email protected]", "user_name": "user1", "admin": false }, "relationships": { "token": { "data": { "type": "tokens", "id": "Qcg6yI1a5qCxXgKWtSAbZ2MIHFChHAq0Vc1Lo4TX", } } } }, "included": [{ "type": "tokens", "id": "Qcg6yI1a5qCxXgKWtSAbZ2MIHFChHAq0Vc1Lo4TX", "attributes": { "expires_in": 3600 } }] }

그런 다음 우리는 token.id 를 사용하여 라이브러리의 Authorization 헤더를 설정하고 사용자를 반환합니다. 이는 이전에 했던 것처럼 User.find() 를 통해 사용자를 요청하는 것과 동일합니다.

이제 User.authenticate(email, password) 를 호출하면 응답으로 인증된 사용자를 수신하고 향후 모든 요청은 액세스 토큰으로 승인됩니다.

ActiveResource.js는 신속한 JavaScript SDK 개발을 가능하게 합니다.

이 자습서에서는 ActiveResource.js를 사용하여 JavaScript SDK를 빠르게 빌드하여 API 리소스 및 다양하고 때로는 복잡한 관련 리소스를 관리할 수 있는 방법을 살펴보았습니다. ActiveResource.js에 대한 README에서 이러한 모든 기능과 더 많은 문서를 볼 수 있습니다.

이러한 작업을 쉽게 수행할 수 있고 필요에 맞는 경우 향후 프로젝트에 내 라이브러리를 사용(및 기여도 할 수 있음)하기를 바랍니다. 오픈 소스 정신으로 PR은 언제나 환영입니다!