V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
banxi1988
V2EX  ›  程序员

向下工作法的一点思考:文档即代码

  •  
  •   banxi1988 ·
    banxi1988 · 2018-07-20 07:36:46 +08:00 · 5820 次点击
    这是一个创建于 2305 天前的主题,其中的信息可能已经有所发展或是发生改变。

    2006 的时候,amazon CTO 在一篇文章中介绍了向下工作法(或者有也有翻译成向后工作法)

    https://www.allthingsdistributed.com/2006/11/working_backwards.html

    向下工作法,简而言之就是下面的流程:

    1. 先写宣传稿
    2. 再写 FAQ
    3. 再定义用户体验
    4. 再写用户手册

    走完这 4 步之后,对于要做的产品应该是相当的清晰了。

    我看了之后深以为然。

    然后分享我的一个思考:文档即代码

    这一点对于前后端 API 模块的开发来说相当适用。 也就是说,正确良好的工作过程应该是,先写好 API 文档,再通过 API 文档生成前端的 JS/TS 代码。 通过 API 文档生成后端代码。

    前后端的 API 模块都应该遵从这样一个逻辑。

    1. 先写 API 文档。
    2. 通过 API 文档生成 代码,(需要时初始手写代码)
    3. 更新 API 文档
    4. 再根据 API 文档更新前后端代码。
    5. ...

    它带来的好处:

    1. API 文档和前后端的代码,能保持高度一致
    2. 通过代码自动生成基本的代码,减少工作量(大部分的 Domain Model, 和 基本 API 接口请求及响应都应该自动生成)
    3. 方便批量修改。

    API 文档可以采用 Swagger 的文档。

    24 条回复    2018-07-20 14:29:24 +08:00
    mofe
        1
    mofe  
       2018-07-20 07:52:44 +08:00 via iPhone
    其实就是先写测试再写代码……
    johnnie502
        2
    johnnie502  
       2018-07-20 08:06:55 +08:00
    BDD/TDD 请了解一下...
    virusdefender
        3
    virusdefender  
       2018-07-20 08:52:01 +08:00   ❤️ 1
    scnace
        4
    scnace  
       2018-07-20 09:05:21 +08:00 via Android
    LZ 你要的就是 protobuf 啊 BDD 和 TDD 对业务密集型的应用感觉还是有点勉强 不知道大家是怎么做的
    BearD01001
        5
    BearD01001  
       2018-07-20 09:06:34 +08:00 via iPhone
    亚马逊先发软文再开发了解一下?
    janxin
        6
    janxin  
       2018-07-20 09:58:08 +08:00
    @scnace 还好吧,勉强在哪里?
    TommyLemon
        7
    TommyLemon  
       2018-07-20 10:25:30 +08:00
    根据文档生成代码,已经有开源方案了
    <img src="http://apijson.org">

    后端接口和文档自动化,前端(客户端) 定制返回 JSON 的数据和结构!
    <img src="https://github.com/TommyLemon/APIJSON">
    创作不易,GitHub 右上角点 Star 支持下吧,谢谢^_^
    Raymon111111
        8
    Raymon111111  
       2018-07-20 10:29:03 +08:00
    业务逻辑复杂到一定得有文档

    很常见
    kurtchen
        9
    kurtchen  
       2018-07-20 10:32:42 +08:00
    等写起来会发现文档有时候也不是那么详尽;特别是大型应用
    lastpass
        10
    lastpass  
       2018-07-20 10:35:10 +08:00 via Android
    然而实际情况是 用户改需求了。
    md 又要改代码又要改文档。
    feverzsj
        11
    feverzsj  
       2018-07-20 10:35:53 +08:00
    文档是不可能写的,项目结束都不可能写文档的,写了也没用,不写的话,公司反而更依赖你
    zhengxiaowai
        12
    zhengxiaowai  
       2018-07-20 10:37:46 +08:00
    理想很好啊,现实很残酷
    lastpass
        13
    lastpass  
       2018-07-20 10:39:32 +08:00 via Android
    什么,还有一周项目就要交付了。
    我们一行代码都没有写。
    管项目的领导你心里没点笔数吗?
    先做出个 demo 去应付一下吧。
    文档?我 demo 都不一定能写完。
    tingyunsay
        14
    tingyunsay  
       2018-07-20 10:42:53 +08:00
    @feverzsj 哈哈,以后跳槽交接的时候能交接半年 o( ̄ε ̄*)
    feverzsj
        15
    feverzsj  
       2018-07-20 10:46:33 +08:00
    @tingyunsay 辞职顶多一个月,公司没有权力不让你跳槽
    zhaogaz
        16
    zhaogaz  
       2018-07-20 10:56:09 +08:00
    不知道有什么可思考的,前人的书里面早就写了,多看看书
    ml1344677
        17
    ml1344677  
       2018-07-20 11:04:23 +08:00
    测试驱动开发啊 快速开发原型
    ofooo
        18
    ofooo  
       2018-07-20 11:10:55 +08:00
    楼主,请问怎么根据文档 api 自动生成代码? api 用什么写?
    还是说只是先有了文档 api 再手工写代码?
    chenyu8674
        19
    chenyu8674  
       2018-07-20 11:11:41 +08:00   ❤️ 2
    PM:”销售已经跟客户那边把牛逼吹出去了,这需求你们技术必须得做,怎么实现我不管,明天上线“

    向下工作法+敏捷开发,天朝领先世界几十年( doge )
    banxi1988
        20
    banxi1988  
    OP
       2018-07-20 11:56:56 +08:00
    @ofooo #18 比如你用 swagger 的文档格式描述 API 的话。
    1 ) swagger 官方网站 本身提供了一系列的工具可以生成各种前后端代码。
    2 )可根据 API 文档 (json 格式,或 yaml 格式)生成(前后端代码)。

    我自己也再做生成前后端代码的脚本。前端脚本基本实现过了。 后端要等等(因为最近没做后端)
    specita
        21
    specita  
       2018-07-20 12:15:33 +08:00
    理想很美好,现实.... 首先你得有一群能实践你想法的队友...
    shyangs
        22
    shyangs  
       2018-07-20 13:03:42 +08:00
    老外就没遇过需求都讲不清楚,说明天要验收的 PM 呀

    ::doge::
    mcfog
        23
    mcfog  
       2018-07-20 13:18:57 +08:00 via Android   ❤️ 1
    个人更倾向反过来,代码生成文档,毕竟让程序员写代码和让程序员写文档的难度差了不止一个数量级
    A555
        24
    A555  
       2018-07-20 14:29:24 +08:00   ❤️ 1
    客户:虽然我想做什么都不知道,但是你必须要满足我。
    我我不知道我要做成什么样啊,不然我找你们干嘛
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   2684 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 30ms · UTC 07:01 · PVG 15:01 · LAX 23:01 · JFK 02:01
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.