您如何知道两个不同版本之间接口的差异？

Question

我正在研究一些php库.我想跟踪类库接口的变化.

• 是的,我正在使用GIT.但差异产生的信息比我需要的多.

• 我试图用phpDocumentor比较两个版本.

  phpdoc项目:parse -d文件夹

生成具有项目接口结构的xml文件.我可以将此xml文件与另一个文件进行比较.但这些包含的信息比我想要的多.像行号,文件哈希等.

所以,我想比较两个提交,分支甚至分支,并找出它们的接口的差异.

比较示例:http://pastebin.com/1H61dJBT

了解何时更改主要版本也很重要.

进行不兼容的API更改时的MAJOR版本...

http://semver.org/spec/v2.0.0.html

Answer 1

清楚的diff报告文本行方面的差异。软件是根据代码结构来定义的。源代码作为文本行和源作为结构之间的不匹配导致 diff 的输出难以理解。

您可以将接口定义与语义设计（我公司的）进行比较 SmartDifferencer进行比较。

这报告了将一段 (PHP) 代码转换为另一段代码时对代码结构（而非行）进行的最少编辑。接口函数名称的更改、插入或删除的参数都变得非常明显。换行符不相关，不会影响 SmartDifferencer 的结果；评论也不是，除非你坚持这样做。（SmartDifferencer 不限于 PHP；有适用于多种语言的版本）。

编辑：OP 想知道 SmartDifferencer 在接口更改的特定示例（PHP 文件之前和之后）上做了什么。接下来是他的两个示例文件、它们的 SmartDifferencer 输出和 Unix-diff 输出。我注意到这些非常小的示例文件中有很多变化。

第一个界面：

<?php
// ----- first version -----
namespace vendor\package;

class someClass
{
private $c;
public function __construct($a, $b)
    {
    $c = $a + $b;
    }
/**
 * @return string
 */
public function returnC()
    {
    return $this->c;
    }
public function saySomething()
    {
    echo 'something';
    }
}

修改后的接口文件

<?php
// ----- second version -----
namespace vendor\package;

class someClass
{
private $a, $b;

public function __construct($a, $b)
    {
    $this->a = $a;
    $this->b = $b;
    }

public function saySomething($something = 'something')
    {
    echo $something;
    }

/**
 * @return integer
 */
public function returnC()
    {
    return $this->a + $this->b;
    }

}

智能差分器输出（MN 表示“M 行，N 列”）：

C:>DMSSmartDifferencer PHP~PHP5 \temp\first_version.php \temp\second_version.php
Copyright (C) 2009-2012 Semantic Designs; All Rights Reserved
PHP~PHP5 SmartDifferencer Version 1.0.14
Copyright (C) 2012 Semantic Designs, Inc; All Rights Reserved; SD Confidential
Powered by DMS (R) Software Reengineering Toolkit
*** Unregistered SmartDifferencer Version 1.0
*** Operating with evaluation limits.

*** Parsing file C:/temp/first_version.php ...
*** Parsing file C:/temp/second_version.php ...
*** Creating suffix tree ...
*** Determining maximal pairs ...
*** Sorting maximal pairs ...
*** Determining differences ...
*** Printing edits ...
Substitute 7.13-7.14 by 7.13-7.18
<            $c
>            $a, $b
Substitute 10.9-10.21 by 11.9-12.22
<        $c = $a + $b;
>        $this->a = $a;
>        $this->b = $b;
At 15.12 insert 15.12-18.9 moving 19.21-19.32 to 15.21-15.32
>           function saySomething($something = 'something')
>        {
>        echo $something;
>        }
Delete 15.12-18.9 at 15.12 moving 15.21-15.27 to 23.21-23.27
<           function returnC()
<        {
<        return $this->c;
<        }
At 19.21 insert 23.21-23.27 moving 15.21-15.27 to 23.21-23.27
>                    returnC
Delete 19.21-19.32 at 23.21 moving 19.21-19.32 to 15.21-15.32
<                    saySomething
Substitute 21.9-21.25 by 25.9-25.35
<        echo 'something';
>        return $this->a + $this->b;
Exiting with final status 1.

您应该看到 SmartDifferencer 专注于代码结构中的增量，而不是行中的增量。您注意到的第一件事是 SmartDifferencer 完全忽略了注释，因为它们对代码的作用没有影响。

但在下面的 Unix diff 中最明显的例子是多重 diff，它将一个函数末尾的 delta 与另一个函数开头的 delta 集中在一起；没有程序员以这种方式解释代码中的差异。当试图理解真正改变的内容时，这种混乱的差异会导致阅读混乱。

Unix 风格 diff 的输出：

C:>diff \temp\first_version.php \temp\second_version.php
2c2
< // ----- first version -----
---
> // ----- second version -----
7c7,8
<     private $c;
---
>     private $a, $b;
>
10c11,17
<         $c = $a + $b;
---
>         $this->a = $a;
>         $this->b = $b;
>         }
>
>     public function saySomething($something = 'something')
>         {
>         echo $something;
11a19
>
13c21
<      * @return string
---
>      * @return integer
17,21c25
<         return $this->c;
<         }
<     public function saySomething()
<         {
<         echo 'something';
---
>         return $this->a + $this->b;
22a27
>

SmartDifferencer 和 diff 都不会告诉您接口的行为发生了变化，因为它所依赖的代码发生了变化。做到这一点的唯一方法是对直接或间接支持接口的所有代码进行静态语义分析，这是一个更难的问题。