EDUSOHO踩坑筆記之四十七：API 開發文檔

• 介紹
• 路由
• 注解
• 異常
• API擴充
• 測試
• 最佳實踐

TODO

• 多版本控制
• OAuth 2.0認證 RFC6749
• 沒有認證的話，接口不能翻頁
• app 請求日志調優
• n+1查詢問題排查
• token過期的解決方案
• 新的Resource尋址解決方案
• 将API重構成架構，參考silex
• 重構oauth2 bundle，去掉ORM
• api session 解決方案，session統一

介紹

ES

API

 遵循 

REST

 的最佳實踐開發的，這裡隻介紹如何在 

ES

 開發接口，怎麼使用不做介紹，如果還不知道如何使用， 可以參考文檔。

路由

API 實作了自動路由的功能，不需要自己寫路由，隻要在相應的目錄下面建立相應的 

PHP

 檔案即可。

ApiBundle下的接口路由定義

Resource類目錄為ApiBundle/Api/Resource

規則如下：

URL	類和方法	描述
GET /api/courses	Course/Course::search	查詢多個課程,或者分頁查詢
GET /api/courses/{courseId}	Course/Course::get	擷取單個課程資訊
POST /api/courses	Course/Course::add	建立課程
PATCH /api/courses/{courseId}	Course/Course::update	修改課程
DELETE /api/courses/{courseId}	Course/Course::remove	删除課程
GET /api/courses/{courseId}/members	Course/CourseMember::search	擷取課程下的學員
GET /api/courses/{courseId}/members/{memberId}	Course/CourseMember::get	擷取單個學員資訊
POST /api/courses/{courseId}/members	Course/CourseMember::add	添加課程學員
PATCH /api/courses/{courseId}/members/{memberId}	Course/CourseMember::update	修改學員資訊
DELETE /api/courses/{courseId}/members/{memberId}	Course/CourseMember::remove	删除課程學員

插件下的接口路由定義

Resource類目錄為{PluginName}/Api/Resource

eg: VipPlugin/Api/Resource

URL 和ApiBundle的差不多,不過前面需要加上/plugins/{pluginName}

URL	類和方法	描述
GET /api/plugins/vip/vip_levels	VipLevel/VipLevel::search	查詢所有的vip等級
GET /api/plugins/vip/vip_levels/{levelId}	VipLevel/VipLevel::get	擷取單個vip等級資訊

注解

ApiConf

在 API 調用前會使用的注解，目前提供了一個接口是否需要認證登陸的功能，預設所有接口都需要認證身份

使用方式：

isRequiredAuth=false

 即是表示該接口不需要認證

1. class Course extends AbstractResource

2. {

4. public function get(ApiRequest $request, $courseId)

5. {

6. ......

7. }

8. }

ResponseFilter

該注解是用來選擇接口傳回值的過濾器

使用方式：

1. lass MeCourseMember extends AbstractResource

2. {

4. public function get(ApiRequest $request, $courseId)

5. {

6. return $courseMember;

7. }

$courseMember

 會使用 

ApiBundle\Api\Resource\Course\CourseMemberFilter

 這個 

filter

 過濾屬性

異常

請在 

Resource

 類裡抛 

Symfony\Component\HttpKernel\Exception\HttpException

 的執行個體，這些異常類會傳回正确的 

HTTP

 狀态碼

1. use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

2. ...

3. throw new NotFoundHttpException('教學計劃不存在', null, ErrorCode::RESOURCE_NOT_FOUND);

4. ...

API 擴充

API 的擴充非常簡單，目前提供兩種方式擴充 API

插件 API 擴充

插件的 API 擴充不需要做任何配置，隻需目錄和 ApiBundle 一緻即可

比如：

1. <?php

2. namespace VipPlugin\Api\Resource\VipLevel;

3. use ApiBundle\Api\Resource\Resource;

4. use Symfony\Component\HttpFoundation\Request;

5. class VipLevel extends Resource

6. {

7. public function search(Request $request)

8. {

9. return $this->service('VipPlugin:Vip:LevelService')->findEnabledLevels();

10. }

11. }

CustomBundle API 擴充

CustomBundle API 擴充也很簡單，隻需要增加一行代碼即可，在 CustomBundle 類的 boot 方法把 API 的命名空間注冊到 

api.resource.manager

 就可以。 注冊進來的 API 命名空間，支援 API 重寫的機制，隻要路由相同，會優先使用 CustomBundle 下的 API

1. $this->container->get('api.resource.manager')->registerApi('CustomBundle\Api');

測試

現在 API 的內建測試使用的 

Newman

 來做，在 

tests/api/Newman

 目錄下，如何增加自己的 API 測試，這裡就不贅述了，自行研究。

最佳實踐

URL規範

• 資源都要加上s,表示是集合的概念
• 如果資源是兩個單詞,使用_分割,比如vip等級,vip_levels