• 这篇文章里推荐的很多个都还不错 https://colorlib.com/wp/free-bootstrap-admin-dashboard-templates/ 我比较喜欢的是 AdminLTE 以及 Gentellela。 另外 CoreUI 也不错 https://coreui.io/。 至于有没有基于 Rails 的,github 帮助你

  • 为什么非要这么设计呢?这样设计交互的需求是什么? actioncable 的方式本质上是走 websocket 嘛,让服务器端来负责 Push。actioncable 不行,那就 faye 之类的。

  • 大家愉快的一致同意 PHP 才是世界上最好的语言

    这是重点,会考,先赶紧拿个小本本抄下来。

  • 头像扁了

  • 信息这么少,我只能认为是楼主错觉了。

  • API 文档这个东西,就我自己而言,用过几个不同的工具,各有特点,简单捋捋:

    Swagger

    其实 Swagger 本身只是一种 API Specification 语法,基于 JSON 格式,如果是完全按照语法约束手写一份 Swagger API 文档,估计会把人整疯。很多时候谈到 Swagger,其实大家更多是说的 Swagger API specification generator + Swagger UI,比如 Grape 就有开箱即用的 grape-swagger。这类方案于我而言,最大的问题是需要在代码中写文档,对于文档先行的团队开发协作来说,这种方式有点本末倒置,另外就是会将文档和代码混在一起,一个 controller 文件的行数,轻轻松松成百上千行。除此之外,使用者还需要熟悉这类 Swagger API specification generator 定义的 DSL 或者特殊的标记语法,更别说可能某些包的实现还有各种配置要求,都是学习的成本,还没有通用性,换个包或者换个语言就又不一样了。
    官方的随便找的一个实例:

    desc 'Attach a field to an entity through a PUT',
        success: [
          { code: 201, model: Entities::UseResponse, message: 'Successfully created' },
          { code: 204, message: 'Already exists' }
        ],
        failure: [
          { code: 400, message: 'Bad request' },
          { code: 404, message: 'Not found' }
        ]  
    put do
      # your code comes here
    end
    

    apipie-rails

    apipie-rails 是我继 swagger 之后使用过的另一个文档工具,如名字所言,也是在 Rails 项目中集成。特点是比 swagger 轻量,DSL 设计主要针对 Restful API 而生,但是仍然需要熟悉一套它的 DSL,概念还挺多,有个比较完整的官方示例:

    resource_description do
      short 'Site members'
      formats ['json']
      param :id, Fixnum, :desc => "User ID", :required => false
      param :resource_param, Hash, :desc => 'Param description for all methods' do
        param :ausername, String, :desc => "Username for login", :required => true
        param :apassword, String, :desc => "Password for login", :required => true
      end
      api_version "development"
      error 404, "Missing"
      error 500, "Server crashed for some <%= reason %>", :meta => {:anything => "you can think of"}
      error :unprocessable_entity, "Could not save the entity."
      returns :code => 403 do
         property :reason, String, :desc => "Why this was forbidden"
      end
      meta :author => {:name => 'John', :surname => 'Doe'}
      deprecated false
      description <<-EOS
        == Long description
         Example resource for rest api documentation
         These can now be accessed in <tt>shared/header</tt> with:
           Headline: <%= headline %>
           First name: <%= person.first_name %>
    
         If you need to find out whether a certain local variable has been
         assigned a value in a particular render call, you need to use the
         following pattern:
    
         <% if local_assigns.has_key? :headline %>
            Headline: <%= headline %>
         <% end %>
    
        Testing using <tt>defined? headline</tt> will not work. This is an
        implementation restriction.
    
        === Template caching
    
        By default, Rails will compile each template to a method in order
        to render it. When you alter a template, Rails will check the
        file's modification time and recompile it in development mode.
      EOS
    end
    

    apipie-rails 从我个人角度,主要的特点是比 swagger-grape-rails 轻量,其他一些我所不喜欢的点,两者都是臭味一致。

    slate

    事实上,上面两个工具并不是我特别想要介绍的,因为用过之后,总觉得心里别扭。去年偶然间发现了一个基于 Markdown 的 API 文档工具,Slate,这玩意非常轻量,而且是 Markdown,并且基本没有太多复杂的语法约束,我个人非常喜欢。基于 Markdown 语法的 API 文档其实也很多选择,比如 API Blueprint,但是后者比较麻烦的是仍然定义了过多的语法约束,比如官网首页的实例:

    # Data Structures
    
    ## Blog Post (object)
    + id: 42 (number, required)
    + text: Hello World (string)
    + author (Author) - Author of the blog post.
    
    ## Author (object)
    + name: Boba Fett
    + email: fett@intergalactic.com
    
    # Blog Posts [/posts]
    
    ## Retrieve All Posts [GET]
    + Response 200 (application/json)
        + Attributes (array[Blog Post])
    

    从 Slate 的语法上看,Slate 基本没有语法约束,基本上是完整的自由,生成的 HTML 页面也非常简洁漂亮。

    现在我所在的公司并没有 Ruby 的技术栈,所以我用的是 Slate 的 Python 版本 plate,结合 GitLab CI 以及公司的 Ceph,实现每次改完文档 git push 之后,就自动在 GitLab CI runner 里构建好静态网页,上传到公司 Ceph(兼容 AWS S3 API 的一套分布式文件系统),就完成自动更新文档了。

    使用 Slate 或者 Plate,满足了我们团队文档先行的协作流程,同时文档和代码分离,语法也非常轻便,就是普通的 Markdown 语法。

    小结

    不同的工具各有利弊,虽然我个人优先考察 Slate,但是我仍然建议根据项目实际情况来选型,比如我们有另外一个团队,前端希望通过 API specification 来自动生成代码,在这种前提下,我就更支持类似 Swagger 这类有强约束的 API 文档规范。

    文档只是为了沟通,找到一种方便 API 使用方以及实现方之间沟通,同时维护成本也低的方案,才是目的。更甚者,如果一份 API 文档的设计,需要双方标注讨论,那我觉得类似 Confluence 或者 Google docs 都是可以考虑的方案。从来没有放诸四海皆准的所谓最好的工作,都是在工作中不断比较最后才能知道哪个选型最合适。

  • 这个文章的背景过去已经比较久,内容可能已经和现在的方案相去甚远,就此结帖,不再讨论。内容仅供参考!

  • @Rei @huacnlee @jasl 43楼这位哥算不算打广告,上个月才注册的号,在社区回帖都是清一色的回答?

  • 如果是简单的需求,比如对外部服务请求方式单一,我觉得 net/http 够了,否则,我觉得哪个轻量用哪个,或者是哪个的设计简单用哪个,这会决定后面你排查问题的难易程度。一般来说,库本身性能是我最后考虑的因素,毕竟对于一个外部请求来说,如果不是很高频,代码本身的性能根本不是什么明显的影响因素。