几个建议(我可以协助完成)

[pluveto]

首先第一步, 注释规范化. . 建议使用apidocjs的方案. 比如下面是我的代码:

    /**
     * @api {post} /auth/register/email 邮箱注册
     * @apiDescription 注册时, 请求体将不可避免地用明文传参.所以建议开启SSL.
     * @apiVersion 2.0.0
     * @apiPermission none
     * @apiName registerByEmail
     * @apiGroup Auth
     *
     * @apiParam {String{3..16}} username  用户名.
     * @apiParam {String{..32}} email  用户邮箱.
     * @apiParam {String{6}} captch  验证码.
     * @apiParam {String} password  密码.
     *
     * @apiSuccessExample 成功响应:
            {
                "ret": 200,
                "data": {},
                "msg": ""
            }
     */
    public function registerByEmail()
    {
        $domain = new Domain();
        /** ============== 格式检查 ============== */
        /** ------- 用户名检查 ------- */
        $this->username = trim($this->username);
        if (!\App\Helper\Validator::checkUsernameFormat($this->username)) {
            throw new BadRequestException('用户名格式错误, 请检查用户名格式是否正确. 只可以含有?.@_所有中英文和emoji.');
        }
        /** ------- 邮箱检查   ------- */
        $this->email = trim($this->email);
        if (!\App\Helper\Validator::checkEmailFormat($this->email)) {
            throw new BadRequestException('邮箱格式错误, 必须形如 [email protected] 的格式');
        }
        /** ============== 正式检查 ============== */
        // 检查可用性(重复)
        if (!$domain->isEmailAvailable($this->email)) {
            throw new BadRequestException('邮箱已被使用');
        }
        /** ------- captch validating ------- */
        $this->captch = trim($this->captch);
        $correctCaptch = $domain->getLastCaptch($this->email);
        if ($correctCaptch == null) {
            throw new BadRequestException('未发送验证码');
        }
        if ($this->captch != $correctCaptch) {
            throw new BadRequestException('验证码错误或过期');
        }
        /** ------- password validating ------- */
        // 密码不进行 trim()
        /** ------- 完成注册 ------- */
        $domain->registerUserByEmail($this->username, $this->email, $this->password, 1);

        // 目前规定, 失败才返回消息
        //\PhalApi\DI()->response->setMsg("注册成功");

        return array();
    }

1. 在目前的设计中, getRules 和 API 实现距离太远, 无论是查找和修改都麻烦, 降低了开发效率. 建议直接从注释中读取规则.
2. 建议能够从注释直接生成fastroute的配置. 比如上面这个就是post方式, 地址为/auth/register/email
3. 建议直接从注释中判断执行权限, 比如这里 @apiPermission none, 就表示任何人都有权限.

apidoc 已经能够直接生成json, 读取json再生成相应所需php文件, 并不困难.

[phalapi]

这是针对PhalApi，还是针对fastroute的优化？

[pluveto]

这是针对PhalApi，还是针对fastroute的优化？

都算是吧. 具体来说, 修改规则的获取方式属于针对phalapi, POST/GET和路由指定属于针对快速路由, 权限管理属于针对过滤器

[pluveto]

可以利用apidoc转为json, 再从json转为静态php文件, 这样的好处是性能更好. 另一方面, 也可以直接用反射从注释提取规则, 这样的好处是即时修改即时生效.

[phalapi]

这些建议很赞！能否做成扩展，或者可选的优化方案？例如提供一个\PhalApi\ApiDoc 基类，让开发者可选择使用哪种风格？

[pluveto]

那么主要的问题就是getRules()
现在的规则是 \vendor\phalapi\kernal\src\Api.php 通过 getApiRules()调用用户实现的getRules()来获得, di里没有提供注入的选项. 如果要用自动生成法的话, 得把路由规则和验证规则单独抽离到一个文件里. 路由规则倒是可以直接新建一个配置文件, 但是验证规则也新增配置文件的话, 可能改动比较大

[phalapi]

改动到底层，是会调整较大，包括在使用上。可以fork一个分支，然后开发一个demo，我们一起看下效果？

[pluveto]

好, 不过这几天我比较忙, 能贡献的代码有限, 我尽力而为

[phalapi]

好的，如有问题，再一起沟通！我们也正在开发PhalApi 2.7.0，可以加下我Q：376741929，我拉你进群一起方便沟通哈。

[pluveto]

嗯, 不过我这里情况所限, 过一久再说吧